Native-Router-Vue/skills/build-with-native-vue-router-v2/SKILL.md

---
name: build-with-native-vue-router-v2
description: Build, integrate, migrate, extend, or debug Vue 3 applications using the routeless @native-vue-router/core-v2 scene, history, gesture-builder, and choreography APIs. Use for new or existing apps that need component-owned navigation, retained Vue instances, forward/back/replace flows, custom interactive transitions, nested scenes or carousels, connected partial drawers, sheets, dialogs, or native-app-like gesture ownership without Vue Router.
---

# Build with Native Vue Router v2

Treat core-v2 as a routeless scene and gesture compositor. Views create other
views from their own mounted origin; there is no route table, URL coordinator,
`RouterView`, or globally current route.

Read [references/core-v2-patterns.md](references/core-v2-patterns.md) completely
before implementing or reviewing an integration. Treat that reference as the
baseline for `0.1.0-experimental.0`. When an installed commit differs, inspect
its exported declarations and package docs before relying on the reference.

## Inspect the target

Identify:

1. Package manager, Vue version, TypeScript settings, and application entry.
2. Existing navigation, gesture, animation, and component-state ownership.
3. Which mounted view should originate each destination and gesture.
4. Which entries must remain mounted for state or scroll restoration.
5. Which flows push, replace, go back, or remain partially connected.
6. Nested gesture owners such as carousels, maps, drawers, and editors.
7. Browser/PWA, Electron, Capacitor, reduced-motion, and accessibility needs.

Do not remove Vue Router from an existing app unless the user explicitly
authorizes that migration. Core-v2 can first own an isolated application
surface or nested feature. Do not mix core-v2 concepts with the legacy
`@native-vue-router/core` runtime.

## Install and establish the scene

Require Vue 3.5 or newer. Install from the Git repository, preferably pinned to
a commit or tag:

```bash
npm install "git+https://git.harvmaster.com/Harvmaster/Native-Router-Vue.git#<commit-or-tag>"
```

Import `@native-vue-router/core-v2/style.css` exactly once. Create an
`OriginScene` from an `originView()` recipe and render one `OriginScene`
component at the owning boundary.

Keep application data in normal Vue state, stores, or props. An `OriginView` is
a construction recipe; a scene node is the particular mounted instance.

## Declare interactions at their origins

Define available gestures and target factories inside the page or component
that owns the interaction:

- Use `forward()` to push a newly mounted history entry.
- Use `back()` to reveal the exact retained previous instance and pop the
  current entry on commit.
- Use `replace()` for one-way completion flows that must skip the current entry
  on future Back.
- Use `above()` and `under()` only for stacking; they do not imply direction.
- Use `origin.perform(action)` for buttons and commands.
- Use an intent without choreography in `.navigate()`, then attach visual
  behavior with `.animate()`.

Prefer `OriginGesture` for one gesture and `OriginGestureSurface` for several.
The surface only forwards pointer events; all recognition, navigation, and
animation policy must remain in the owning component.

Start a builder at `.to` for an anywhere gesture. Add `.from.left()`,
`.from.right()`, `.from.top()`, `.from.bottom()`, or `.from.when()` only when
pointer-down eligibility is constrained. Use CSS percentages or `clamp()` for
responsive edge regions. Mark controls and nested interaction regions with
`data-origin-gesture="ignore"` when the parent recognizer must yield.

## Design choreography deliberately

Keep `effects()` deterministic and side-effect free. Compose geometry through
`frame`, `source`, and `target`; do not mutate application state from an
animation callback.

Use separate reciprocal opening and closing choreographies when their source
and target roles differ. Set `persistAtRest: true` only for a pushed partial
presentation whose progress-1 relationship must remain visible, such as a
two-thirds drawer. Ensure its back choreography begins at exactly the same
visual endpoints.

Use explicit `.complete(({ progress, velocity }) => ...)` policy when product
requirements depend on velocity. Avoid assuming a library default is the
application's UX policy.

## Preserve instance semantics

Every committed push retains the previous Vue instance until it is popped by
Back. Do not add `<KeepAlive>` around scene views or build a second cache.
`replace()` unmounts the replaced entry only after commit. A cancelled
operation restores its origin.

Parked and visually exposed retained entries are inert. Their normal Vue
effects and timers still run, so page components must pause expensive work
using ordinary app state when needed.

Create a nested `OriginScene` when a carousel, deck, or embedded flow needs its
own local component history. Define clear pointer-down regions between parent
and child recognizers; automatic gesture-arena arbitration is not available.

## Verify the result

Run the target formatter, type checker, tests, and production build. Exercise:

- Programmatic and gesture-driven push, Back, and cancellation.
- Replace followed by Back to prove the replaced entry cannot return.
- Rapid chained gestures while earlier springs are settling.
- Component identity, form state, and nested scroll restoration.
- Edge sizing at desktop and mobile widths.
- Nested gesture conflicts and ignored controls.
- Connected partial presentation open, cancelled close, and committed close.
- Reduced motion, keyboard controls, focus isolation, and screen-reader
  isolation.
- Browser console errors and scene diagnostics during held gestures.

Report the component ownership model, history behavior, gestures and
choreographies added, retained-instance implications, and verification results.
Call out URL/hardware-back integration as application-host work rather than
claiming core-v2 provides it.