add initatedBy

.github/workflows/test.yaml

@@ -28,7 +28,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Test
         run: |
-          yarn install
+          npm install
           npm run build
           npm run test:ci
         env:

docs/api/navigate.md

@@ -80,4 +80,9 @@ export async function createUser () {
 
 ## Detecting `navigate` events
 
-`navigate` has two modes: intra-domain navigation and extra-domain navigation. When navigating outside the current origin navigation is done directly, and no `popstate` event is dispatched. When navigating to the current origin a custom `popstate` event is dispatched. The event has a `__tag: 'raviger:navigation'` property is attached to help programmatically distinguish these events from `popstate` events dispatched from other sources, such as the browser **back button**.
+`navigate` has two modes: intra-domain navigation and extra-domain navigation. When navigating outside the current origin navigation is done directly, and no `popstate` event is dispatched. When navigating to the current origin a custom `popstate` event is dispatched. Two properties are attached to the event to help programmatically distinguish these events from `popstate` events dispatched by the browser **back/forward** buttons:
+
+- `__tag: 'raviger:navigation'` — present on all events dispatched by `navigate()`
+- `__method: 'push' | 'replace'` — indicates whether `history.pushState` or `history.replaceState` was used
+
+If you are using `useLocationChange`, the `initiatedBy` field on the `RavigerLocation` object already reflects this distinction — prefer that over reading the event properties directly.

docs/api/useLocationChange.md

@@ -11,6 +11,8 @@ This hook invokes a setter whenever the page location is updated. It uses a `win
 ## API
 
 ```typescript
+export type NavigationInitiator = 'push' | 'replace' | 'pop'
+
 export interface RavigerLocation {
   /** The current path; alias of `pathname` */
   path: string | null
@@ -25,6 +27,14 @@ export interface RavigerLocation {
   hostname: string
   href: string
   origin: string
+  /**
+   * How the navigation was initiated.
+   * - `'push'`: programmatic navigation via `navigate()` (history.pushState)
+   * - `'replace'`: programmatic navigation via `navigate({ replace: true })` (history.replaceState)
+   * - `'pop'`: browser back/forward button (popstate event)
+   * - `undefined`: fired on mount or basePath change, not triggered by navigation
+   */
+  initiatedBy?: NavigationInitiator
 }
 
 export function useLocationChange(
@@ -103,6 +113,39 @@ function Route () {
 }
 ```
 
+## Detecting How Navigation Was Initiated
+
+The `initiatedBy` field on `RavigerLocation` indicates what caused the navigation:
+
+| Value | Cause |
+|---|---|
+| `'push'` | Programmatic call to `navigate()` (adds a history entry) |
+| `'replace'` | Programmatic call to `navigate({ replace: true })` (replaces current history entry) |
+| `'pop'` | Browser back/forward button |
+| `undefined` | Fired on initial mount or basePath change — not a navigation event |
+
+```jsx
+import { useCallback } from 'react'
+import { useLocationChange } from 'raviger'
+
+function App () {
+  const onChange = useCallback(location => {
+    if (location.initiatedBy === 'pop') {
+      console.log('User navigated with browser back/forward')
+    } else if (location.initiatedBy === 'push') {
+      console.log('Programmatic navigation to', location.path)
+    } else if (location.initiatedBy === 'replace') {
+      console.log('Programmatic replace to', location.path)
+    }
+  }, [])
+  useLocationChange(onChange)
+
+  return (
+    // ...
+  )
+}
+```
+
 ## Previous Behavior
 
 Prior to v4 this hook called `setFn` with the path instead of a `RavigerLocation`. If you prefer the previous behavior you can use this wrapper