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

name, description

name

description

build-with-native-vue-router-v2

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 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:

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.