@okyrychenko-dev/react-action-guard-router 0.2.4 → 1.0.0

package/README.md

@@ -1,14 +1,21 @@
 # @okyrychenko-dev/react-action-guard-router
 
+See the [versioned capability matrix](https://github.com/okyrychenko-dev/react-action-guard/blob/main/CAPABILITIES.md) for evaluated peers, reproducible checks, evidence kinds, and limitations.
+
 [![npm version](https://img.shields.io/npm/v/@okyrychenko-dev/react-action-guard-router.svg)](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-router)
 [![npm downloads](https://img.shields.io/npm/dm/@okyrychenko-dev/react-action-guard-router.svg)](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard-router)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 > Router integration for React Action Guard - navigation blocking for React Router, Remix, TanStack Router, and Next.js
 
+Start with the [core-only coordination example](https://github.com/okyrychenko-dev/react-action-guard/tree/main/examples/core-coordination)
+to see one operation affect two independent controls. Add this package when you need its
+integration. [Canonical documentation and local instructions](https://github.com/okyrychenko-dev/react-action-guard/tree/main/packages/docs)
+provide the next learning step.
+
 ## Features
 
-- 🛣️ **Multi-Router Support** - React Router v6+, Remix, TanStack Router, Next.js Pages Router, and best-effort App Router support
+- 🛣️ **Multi-Router Support** - React Router v6.19+, Remix, TanStack Router, limited Next.js Pages Router interception, and App Router unload-only protection
 - 🎯 **Scope-Based Blocking** - Synchronize navigation blocking with UI blocking scopes
 - 🚦 **Condition-Based Blocking** - Block based on boolean conditions or functions
 - 💬 **Custom Dialog Support** - `useDialogState` helper for async confirmation dialogs
@@ -30,12 +37,12 @@ pnpm add @okyrychenko-dev/react-action-guard-router @okyrychenko-dev/react-actio
 
 This package requires the following peer dependencies:
 
-- [@okyrychenko-dev/react-action-guard](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard) ^1.0.1 - The core UI blocking library
+- [@okyrychenko-dev/react-action-guard](https://www.npmjs.com/package/@okyrychenko-dev/react-action-guard) ^2.0.0 - The core UI blocking library
 - [React](https://react.dev/) ^18.0.0 || ^19.0.0
 - One of:
-  - [react-router-dom](https://reactrouter.com/) ^6.0.0 - For React Router or Remix
-  - [@tanstack/react-router](https://tanstack.com/router) ^1.0.0 - For TanStack Router
-  - [next](https://nextjs.org/) ^13.4.0 - For Next.js Pages Router and best-effort App Router support
+  - [react-router-dom](https://reactrouter.com/) ^6.19.0 - For React Router or Remix
+  - [@tanstack/react-router](https://tanstack.com/router) ^1.170.41 - For TanStack Router
+  - [next](https://nextjs.org/) ^13.4.0 - For limited Pages Router interception and App Router unload-only protection
 - [Zustand](https://zustand-demo.pmnd.rs/) - State management (peer dependency of react-action-guard)
 
 ## Quick Start
@@ -45,22 +52,26 @@ This package requires the following peer dependencies:
 The most powerful pattern - synchronize navigation blocking with UI blocking:
 
 ```tsx
-import { useBlocker } from '@okyrychenko-dev/react-action-guard';
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { useActionBlocker } from "@okyrychenko-dev/react-action-guard";
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function PaymentForm() {
   const [isProcessing, setIsProcessing] = useState(false);
 
   // Block UI during payment processing
-  useBlocker('payment-processing', {
-    scope: 'checkout',
-    reason: 'Processing payment...',
-  }, isProcessing);
+  useActionBlocker(
+    "payment-processing",
+    {
+      scope: "checkout",
+      reason: "Processing payment...",
+    },
+    isProcessing
+  );
 
   // Block navigation when the same scope is active
   useNavigationBlocker({
-    scope: 'checkout',
-    message: 'Payment is processing. Please wait.',
+    scope: "checkout",
+    message: "Payment is processing. Please wait.",
   });
 
   // When isProcessing = true, both UI and navigation are blocked
@@ -72,18 +83,27 @@ function PaymentForm() {
 For basic usage without react-action-guard scopes:
 
 ```tsx
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function EditForm() {
   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
 
   useNavigationBlocker({
     when: hasUnsavedChanges,
-    message: 'You have unsaved changes. Leave anyway?',
+    message: "You have unsaved changes. Leave anyway?",
   });
 }
 ```
 
+<details>
+<summary>Detailed reference and integration patterns</summary>
+
+## Canonical reference
+
+Read the [public reference](https://github.com/okyrychenko-dev/react-action-guard/blob/main/packages/docs/src/packages/react-action-guard-router/reference.md)
+and [integration guide](https://github.com/okyrychenko-dev/react-action-guard/blob/main/packages/docs/src/packages/react-action-guard-router/index.md).
+The expandable material below remains available for existing links.
+
 ## API Reference
 
 ### Hooks
@@ -109,7 +129,8 @@ Blocks navigation in router applications based on conditions or scope state.
 - `isIntercepting?: boolean` - Active interception state when the router can expose it
 
 **Available in:**
-- `@okyrychenko-dev/react-action-guard-router/react-router` - React Router v6+ & Remix
+
+- `@okyrychenko-dev/react-action-guard-router/react-router` - React Router v6.19+ & Remix
 - `@okyrychenko-dev/react-action-guard-router/tanstack-router` - TanStack Router
 - `@okyrychenko-dev/react-action-guard-router/nextjs` - Next.js Pages & App Router
 
@@ -118,28 +139,28 @@ Blocks navigation in router applications based on conditions or scope state.
 ```tsx
 // Scope-based blocking
 useNavigationBlocker({
-  scope: 'form',
-  message: 'You have unsaved changes',
+  scope: "form",
+  message: "You have unsaved changes",
 });
 
 // Condition-based blocking
 useNavigationBlocker({
   when: hasChanges,
-  message: 'Discard changes?',
-  onBlock: () => console.log('Navigation blocked'),
-  onAllow: () => console.log('Navigation allowed'),
+  message: "Discard changes?",
+  onBlock: () => console.log("Navigation blocked"),
+  onAllow: () => console.log("Navigation allowed"),
 });
 
 // Multiple scopes
 useNavigationBlocker({
-  scope: ['form', 'validation'],
-  message: 'Form is being validated',
+  scope: ["form", "validation"],
+  message: "Form is being validated",
 });
 
 // Function condition
 useNavigationBlocker({
   when: () => formIsDirty() || hasUnsavedData(),
-  message: 'You have unsaved work',
+  message: "You have unsaved work",
 });
 ```
 
@@ -150,18 +171,35 @@ Helper hook for managing custom confirmation dialogs.
 **Parameters:** None
 
 **Returns:**
+
 - `dialogState: DialogState<TMessage> | null` - Current dialog state
   - `message: TMessage` - The message passed to confirm
   - `isOpen: boolean` - Whether dialog is open
-  - `resolve: (value: boolean) => void` - Internal resolver
+  - `resolve: (value: boolean) => void` - Settle and close this specific dialog
 - `confirm: (message: TMessage) => Promise<boolean>` - Show dialog, returns Promise
 - `onConfirm: () => void` - Resolve dialog with `true`
 - `onCancel: () => void` - Resolve dialog with `false`
 
+Each request settles once: confirmation resolves `true`; cancellation, replacement by
+another `confirm` call, and hook unmount resolve `false`. Calling `dialogState.resolve`
+also closes that dialog. Repeated calls and resolvers captured from an older dialog
+have no effect on a newer dialog.
+
+Effect teardown also cancels and clears the pending dialog when React preserves
+hook state, such as when an `Activity` becomes hidden. Revealing the subtree starts
+with no open dialog and allows new confirmation requests.
+
+`confirm`, `onConfirm`, and `onCancel` retain stable references across renders.
+The hook-level `onConfirm` and `onCancel` always act on the current dialog; use its
+`dialogState.resolve` when a captured callback must belong to a specific dialog.
+
 **Example:**
 
 ```tsx
-import { useNavigationBlocker, useDialogState } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import {
+  useNavigationBlocker,
+  useDialogState,
+} from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function MyComponent() {
   const [hasChanges, setHasChanges] = useState(false);
@@ -169,18 +207,14 @@ function MyComponent() {
 
   useNavigationBlocker({
     when: hasChanges,
-    onConfirm: confirm,  // Returns Promise<boolean>
+    onConfirm: confirm, // Returns Promise<boolean>
   });
 
   return (
     <>
       <form>...</form>
       {dialogState && (
-        <CustomDialog
-          message={dialogState.message}
-          onConfirm={onConfirm}
-          onCancel={onCancel}
-        />
+        <CustomDialog message={dialogState.message} onConfirm={onConfirm} onCancel={onCancel} />
       )}
     </>
   );
@@ -193,37 +227,53 @@ function MyComponent() {
 interface CustomMessage {
   title: string;
   body: string;
-  severity: 'warning' | 'error';
+  severity: "warning" | "error";
 }
 
 const { dialogState, confirm } = useDialogState<CustomMessage>();
 
 useNavigationBlocker({
   when: isDirty,
-  onConfirm: () => confirm({
-    title: 'Unsaved Changes',
-    body: 'Your work will be lost',
-    severity: 'warning',
-  }),
+  onConfirm: () =>
+    confirm({
+      title: "Unsaved Changes",
+      body: "Your work will be lost",
+      severity: "warning",
+    }),
 });
 ```
 
+### Render-time conditions
+
+A function passed as `when` must be a pure condition. Each React render evaluates
+it again, including a stable function created with `useCallback` or one reading a
+ref or external state. Changing a ref or external value alone does not trigger a
+render or refresh protection; arrange a React rerender or subscription.
+`useCallback` is optional and does not cache the condition's result. A true
+condition or a blocked `scope` enables protection (OR semantics).
+
+This correction affects consumers whose stable predicates previously retained a
+stale result: protection now follows the current result after rerender. Router
+capabilities are unchanged; Next App Router protects document unload only and
+does not intercept same-document navigation.
+
 #### `usePrompt(message, when)` (React Router only)
 
 Simple API similar to React Router v5's `usePrompt`.
 
 **Parameters:**
+
 - `message: string` - Confirmation message
 - `when: boolean` - Condition to activate blocking
 
 **Example:**
 
 ```tsx
-import { usePrompt } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { usePrompt } from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function MyForm() {
   const [hasChanges, setHasChanges] = useState(false);
-  usePrompt('You have unsaved changes', hasChanges);
+  usePrompt("You have unsaved changes", hasChanges);
 }
 ```
 
@@ -232,17 +282,18 @@ function MyForm() {
 Standalone hook for blocking browser unload events (tab close, refresh).
 
 **Parameters:**
+
 - `when: boolean` - Condition to activate blocking
 - `message?: string` - Optional custom message (default: "Are you sure you want to leave?")
 
 **Example:**
 
 ```tsx
-import { useBeforeUnload } from '@okyrychenko-dev/react-action-guard-router';
+import { useBeforeUnload } from "@okyrychenko-dev/react-action-guard-router";
 
 function MyComponent() {
   const [hasUnsavedWork, setHasUnsavedWork] = useState(false);
-  useBeforeUnload(hasUnsavedWork, 'You have unsaved work');
+  useBeforeUnload(hasUnsavedWork, "You have unsaved work");
 }
 ```
 
@@ -257,12 +308,12 @@ This utility works independently of any router and can be used in any React appl
 Full support with React Router v6's `useBlocker` hook.
 
 ```tsx
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function MyComponent() {
   useNavigationBlocker({
     when: isDirty,
-    message: 'Discard changes?',
+    message: "Discard changes?",
   });
 }
 ```
@@ -272,33 +323,39 @@ function MyComponent() {
 
 ### TanStack Router
 
-Full support with TanStack Router's history blocking.
+Uses TanStack Router's native `useBlocker` for in-app transitions. Requires TanStack Router 1.170.41 or newer; earlier versions are no longer declared supported.
 
 ```tsx
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/tanstack-router';
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/tanstack-router";
 
 function MyComponent() {
   useNavigationBlocker({
     when: isDirty,
-    message: 'Discard changes?',
+    message: "Discard changes?",
   });
 }
 ```
 
-Async `onConfirm` is supported and evaluated once per blocked navigation attempt.
+Sync and async `onConfirm` are evaluated once per blocked navigation attempt. Active blocking without a message denies silently and emits `onBlock`. Denial, rejection, and thrown confirmation errors retain the current location. Acceptance permits that transition once and emits `onAllow`; subsequent transitions remain protected. Superseded confirmations and results received after unmount or authorization option changes cannot authorize navigation. Replacing `when` or changing the effective `scope` contents invalidates a pending confirmation even when the computed blocking condition remains true. Equivalent scope arrays preserve the attempt: array identity, order, and duplicates do not affect scope comparison. Changes to observer callbacks `onBlock` and `onAllow` do not invalidate a pending confirmation; the attempt retains the callbacks it started with.
+
+`scope` and `when` retain their existing OR behavior. `blockBrowserUnload` controls native TanStack unload protection. Its one-shot bypass suppresses a second browser prompt after accepted document navigation; later unloads remain protected. The adapter does not register a separate shared unload handler. Unload uses a browser-controlled prompt, not asynchronous custom confirmation.
+
+**Not-found limitation:** In the verified TanStack Router 1.170.41, navigation from an unmatched URL (`__notFound__`) to a matched route bypasses native `useBlocker` before this adapter's callback runs, even with `when: true` or an active scope. `onBlock`, `onConfirm`, and `onAllow` are not called for that transition. A blocker mounted above the not-found UI therefore cannot protect this exit; do not rely on it to guard unsaved work there. Subsequent matched-to-matched navigation remains guarded. This is upstream behavior introduced by [the upstream TanStack Router change](https://github.com/TanStack/router/pull/4917), covered by real-router tests for both condition sources. The adapter does not compensate for the bypass.
+
+Compatibility tests exercise the public hook at 1.170.41 with real memory history for in-app navigation and browser history in the DOM test environment for unload protection. The unload tests intercept document location assignment and dispatch beforeunload events; they do not establish browser prompt UI behavior. Separate Playwright tests verified same-document back/forward on matched routes in Chrome 154.0.8037.57 on 2026-10-03: custom-dialog cancellation retains the original route and URL, confirmation reaches the intended destination once, and subsequent history attempts remain protected. This evidence does not establish other browsers or cross-document history transitions. Reproduction steps, evaluated versions, and result artifacts are documented in [browser-history verification](https://github.com/okyrychenko-dev/react-action-guard/blob/main/packages/router/browser/README.md). The verified floor was raised from 1.170.28 because the older locked router-core/history combination skipped blockers for external navigation. The native API is documented in [TanStack navigation blocking](https://tanstack.com/router/latest/docs/guide/navigation-blocking).
 
 ### Next.js Pages Router
 
-Full support with Next.js router events.
+Limited interception through Next.js router events.
 
 ```tsx
 // pages/edit.tsx
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/nextjs';
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/nextjs";
 
 function EditPage() {
   useNavigationBlocker({
     when: isDirty,
-    message: 'Discard changes?',
+    message: "Discard changes?",
   });
 }
 ```
@@ -306,39 +363,50 @@ function EditPage() {
 **Async `onConfirm` behavior:**  
 Pages Router does not allow pausing transitions. When you return a Promise from `onConfirm`, the hook cancels the current navigation and re-attempts it via `router.push(url)` if confirmed. This may not preserve original transition options (e.g., `shallow`, `scroll`, `locale`).
 
+Only the current confirmation attempt can resume navigation. Cleanup, disabling protection, or changing the protected scope or message invalidates pending answers. Callback rerenders and equivalent scopes preserve the current attempt. `onAllow` fires once for an accepted attempt; the replay permission is consumed once and cleared when the retry finishes or another URL is attempted.
+
+Selected packed Next 15.5.23 production Pages/App browser evidence and its limitations are recorded in the [runtime guide](https://github.com/okyrychenko-dev/react-action-guard/blob/main/scripts/next-runtime/README.md) and [capability matrix](https://github.com/okyrychenko-dev/react-action-guard/blob/main/CAPABILITIES.md). This does not establish every supported peer or navigation option.
+
 ### Next.js App Router
 
-Best-effort support only. Browser unload protection works, but App Router does not expose an official navigation-blocking API.
+Unload-only protection: the hook requests a browser `beforeunload` prompt, subject to browser policy. It does not intercept same-document `Link`, `push`, or back/forward navigation, and does not evaluate `onConfirm`. App Router does not expose an official navigation-blocking API.
 
 ```tsx
 // app/edit/page.tsx
-'use client';
+"use client";
 
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/nextjs';
+import { useState } from "react";
+import { useAppRouterBlocker } from "@okyrychenko-dev/react-action-guard-router/nextjs";
 
-function EditPage() {
-  useNavigationBlocker({
+export default function EditPage() {
+  const [isDirty, setIsDirty] = useState(false);
+
+  useAppRouterBlocker({
     when: isDirty,
-    message: 'You have unsaved changes',
+    message: "You have unsaved changes",
   });
+
+  return <input onChange={() => setIsDirty(true)} />;
 }
 ```
 
 **App Router Limitations:**
-- ✅ Browser back/forward/close/refresh are blocked
+
+- `beforeunload` can request the browser’s native prompt for document unload (close, refresh, or cross-document navigation), subject to browser policy.
+- Same-document App Router back/forward is not intercepted.
 - ❌ `<Link>` component navigation is NOT blocked
 - ❌ `router.push()` is NOT blocked
 
-For full navigation blocking support, use Pages Router.
+Pages Router provides route-event interception with the replay limitations described above.
 
 ## Adapter Capabilities
 
-| Adapter | `isBlocking` meaning | `isIntercepting` | Async `onConfirm` | Caveats |
-| --- | --- | --- | --- | --- |
-| React Router | Blocking condition is armed | Yes | Yes | Best semantic fidelity |
-| TanStack Router | Blocking condition is armed | No | Yes | Depends on history.block integration |
-| Next.js Pages Router | Blocking condition is armed | No | Yes | Re-attempts confirmed navigation with `router.push(url)` |
-| Next.js App Router | Blocking condition is armed | No | Best effort only | No official blocker API from Next.js |
+| Adapter              | `isBlocking` meaning        | `isIntercepting` | Async `onConfirm` | Caveats                                                  |
+| -------------------- | --------------------------- | ---------------- | ----------------- | -------------------------------------------------------- |
+| React Router         | Blocking condition is armed | Yes              | Yes               | Best semantic fidelity                                   |
+| TanStack Router      | Blocking condition is armed | No               | Yes               | Native useBlocker; memory-history transitions verified   |
+| Next.js Pages Router | Blocking condition is armed | No               | Yes               | Re-attempts confirmed navigation with `router.push(url)` |
+| Next.js App Router   | Blocking condition is armed | No               | No                | beforeunload only; no same-document interception         |
 
 ---
 
@@ -353,7 +421,7 @@ function SignupForm() {
 
   useNavigationBlocker({
     when: isDirty,
-    message: 'Your signup progress will be lost. Continue?',
+    message: "Your signup progress will be lost. Continue?",
   });
 }
 ```
@@ -366,14 +434,18 @@ function MultiStepWizard() {
   const [isSubmitting, setIsSubmitting] = useState(false);
 
   // Block UI during submission
-  useBlocker('wizard-submit', {
-    scope: 'wizard',
-    reason: 'Submitting form...',
-  }, isSubmitting);
+  useActionBlocker(
+    "wizard-submit",
+    {
+      scope: "wizard",
+      reason: "Submitting form...",
+    },
+    isSubmitting
+  );
 
   // Block navigation during submission OR if wizard incomplete
   useNavigationBlocker({
-    scope: 'wizard',
+    scope: "wizard",
     when: currentStep < 5,
     message: `You're on step ${currentStep}/5. Exit wizard?`,
   });
@@ -383,22 +455,24 @@ function MultiStepWizard() {
 ### E-Commerce Checkout
 
 ```tsx
-import { useBlockingMutation } from '@okyrychenko-dev/react-action-guard-tanstack';
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { useBlockingMutation } from "@okyrychenko-dev/react-action-guard-tanstack";
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/react-router";
 
 function CheckoutPage() {
   const paymentMutation = useBlockingMutation({
     mutationFn: processPayment,
-    blockingConfig: { scope: 'checkout' },
+    blockingConfig: { scope: "checkout" },
   });
 
   useNavigationBlocker({
-    scope: 'checkout',
-    message: 'Payment is processing. Leaving will cancel the transaction.',
+    scope: "checkout",
+    message: "Payment is processing. Leave this page?",
   });
 }
 ```
 
+UI blocking and navigation confirmation do not cancel the payment request or roll back a transaction. Cancellation, server authorization, and idempotency belong to the application and its backend.
+
 ### File Upload with Progress
 
 ```tsx
@@ -423,31 +497,29 @@ TypeScript-friendly API surface:
 ```typescript
 import type {
   // Core types
-  UseNavigationBlockerOptions,
+  BaseNavigationBlockerOptions,
   NavigationBlockerReturn,
   DialogState,
-  ConfirmationResult,
-  ConfirmationCallbacks,
-} from '@okyrychenko-dev/react-action-guard-router';
+} from "@okyrychenko-dev/react-action-guard-router";
 
 // Router-specific types
-import type { UseNavigationBlockerOptions } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import type { UseNavigationBlockerOptions } from "@okyrychenko-dev/react-action-guard-router/react-router";
 ```
 
 **Typed scopes with `react-action-guard`:**
 
 ```tsx
-import { createTypedHooks } from '@okyrychenko-dev/react-action-guard';
+import { createTypedHooks } from "@okyrychenko-dev/react-action-guard";
 
-type AppScopes = 'form' | 'checkout' | 'navigation';
-const { useBlocker } = createTypedHooks<AppScopes>();
+type AppScopes = "form" | "checkout" | "navigation";
+const { useActionBlocker } = createTypedHooks<AppScopes>();
 
 function MyComponent() {
-  useBlocker('id', { scope: 'form' });  // ✅ Typed in the core package
+  useActionBlocker("id", { scope: "form" }); // ✅ Typed in the core package
 
   useNavigationBlocker({
-    scope: 'form',  // ✅ Reuses the same scope values cleanly
-    message: 'Leave form?',
+    scope: "form", // ✅ Reuses the same scope values cleanly
+    message: "Leave form?",
   });
 }
 ```
@@ -460,10 +532,11 @@ Tree-shakeable by router adapter. Import only what you need:
 
 ```tsx
 // Only React Router code is bundled
-import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router/react-router';
+import { useNavigationBlocker } from "@okyrychenko-dev/react-action-guard-router/react-router";
 ```
 
 **Approximate sizes (minified):**
+
 - Core utilities: ~2 KB
 - React Router adapter: ~2.5 KB
 - TanStack Router adapter: ~2.5 KB
@@ -471,26 +544,27 @@ import { useNavigationBlocker } from '@okyrychenko-dev/react-action-guard-router
 
 ---
 
-## Development
-
-```bash
-# Install dependencies
-npm install
+</details>
 
-# Run tests
-npm run test
-
-# Build the package
-npm run build
-
-# Type checking
-npm run typecheck
+## Development
 
-# Lint
-npm run lint
+This package lives in the [react-action-guard monorepo](https://github.com/okyrychenko-dev/react-action-guard)
+(pnpm workspaces). From the monorepo root:
 
-# Fix lint errors
-npm run lint:fix
+```bash
+# Install dependencies for all packages
+pnpm install
+
+# Run this package's scripts with --filter
+pnpm --filter @okyrychenko-dev/react-action-guard-router run test:run
+pnpm --filter @okyrychenko-dev/react-action-guard-router run build
+pnpm --filter @okyrychenko-dev/react-action-guard-router run typecheck
+pnpm --filter @okyrychenko-dev/react-action-guard-router run lint
+pnpm --filter @okyrychenko-dev/react-action-guard-router run lint:fix
+
+# Or cd into the package and run scripts directly
+cd packages/router
+pnpm run test:run
 ```
 
 ---
@@ -505,12 +579,15 @@ npm run lint:fix
 
 ## Contributing
 
-Contributions are welcome! Please ensure:
+Contributions are welcome! Please ensure, before opening a PR:
 
-1. Tests pass (`npm run test:run`)
-2. Code is properly typed (`npm run typecheck`)
-3. Linting passes (`npm run lint`)
-4. Code is formatted (`npm run format`)
+1. Tests pass (`pnpm run test:run`)
+2. Code is properly typed (`pnpm run typecheck`)
+3. Linting passes (`pnpm run lint`)
+4. Code is formatted (`pnpm run format`)
+5. If the change affects this package's public behavior, add a changeset: `pnpm changeset`
+   (see the [Releasing](https://github.com/okyrychenko-dev/react-action-guard#releasing) section
+   of the monorepo README)
 
 ---