@keenmate/svelte-spa-router 5.2.0-rc01 → 5.2.0-rc02

package/CHANGELOG.md

@@ -5,6 +5,93 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.0-rc02] - 2026-05-01
+
+### Fixed
+- **`ReferenceError: __PACKAGE_NAME__ is not defined` masking real route errors** — The global API setup in `src/lib/index.js` referenced bundler-injected placeholders (`__PACKAGE_NAME__`, `__VERSION__`, `__AUTHOR__`, `__LICENSE__`, `__REPOSITORY__`, `__HOMEPAGE__`) with `typeof X !== 'undefined'` fallbacks. Consumer Vite optimizers (esbuild prebundle) were not preserving the guard, leaving bare references that threw `ReferenceError` at module-init. The error surfaced asynchronously during route activation and masked real errors thrown by route components.
+  - Replaced the placeholder pattern with a direct `import pkg from '../../package.json'` — works universally because npm always ships `package.json` and all modern bundlers handle JSON imports natively.
+  - No consumer-side bundler config required.
+
+- **Svelte 5 `state_referenced_locally` warnings on every consumer dev build** — `Router.svelte` parsed the `routes` prop into `routesList` at script top level, which captures only the initial value. Svelte 5 emitted three `state_referenced_locally` warnings (lines 172, 173, 177) in any consumer's dev console, and silently ignored prop swaps if a consumer ever replaced `routes`.
+  - Wrapped the parse logic in `$derived.by(() => { ... })` so the closure captures `routes` reactively. Warnings are gone and the routes prop is now properly reactive — replacing it rebuilds `routesList` and takes effect on the next navigation.
+  - `findParentRoute()` and `findMatchingRoute()` already read `routesList` per-call, so no other changes were needed.
+
+- **`navigationContext()` was never `null` after any `push()` call, breaking the "no context" check in consumer code** — `push()` and `replace()` internally inject `_routeName` (for referrer tracking) and optionally `__scrollBehavior` (for scroll control) into the stored navigation context. Previously these internal keys leaked through the public `navigationContext()` accessor, so `navigationContext()` returned `{ _routeName: '/path' }` (truthy) instead of `null` even when the consumer hadn't passed any context. Code patterns like `{#if !navigationContext()}` or `if (ctx === null)` silently broke. The `NavigationContextDemo` example was a victim: clicking "Back to List" called `push('/navigation-context-demo')`, expecting `ctx` to become null and the list view to re-render — but `ctx` was `{ _routeName: ... }`, so none of the `{#if}` branches matched and the middle area went blank.
+  - `navigationContext()` now filters out the router's internal keys (`_routeName`, `__scrollBehavior`) and returns `null` if nothing user-visible remains.
+  - Added an internal `getRawNavigationContext()` accessor that returns the full state including internal keys. `Router.svelte` uses this for its own internal reads (referrer-route lookup, scroll-behavior override). Not exposed in the public type declarations.
+  - **Migration:** if you were depending on seeing `_routeName` or `__scrollBehavior` in `navigationContext()` output (you almost certainly weren't), use `getRawNavigationContext()` from utils — but these are internal flags and the contract is that they may change without notice.
+  - vitest coverage in `navigation.test.js`: two new cases assert `navigationContext()` returns `null` after a no-context `push()`, and that user keys pass through while `_routeName` is filtered.
+
+- **`push('/path', {}, queryObject)` and `replace(...)` silently dropped the querystring** — The multi-parameter signature `push(route, params, query, context)` only serialized the `query` object when the first argument was a *named route*. When the first argument was a path string (starting with `/`), the path branch stored `query` on `opts` but the downstream code only read `opts.href`, so the query object was never applied to the URL. The named-route branch worked because it routes through `buildUrl()`, which does the serialization. Existing tests only covered the named-route case and the path case with empty `{}`, so the regression was invisible.
+  - Extracted `serializeQuery(query)` into `helpers/url-helpers.svelte.js` and reuse it in both `buildUrl()` (named branch, behavior unchanged) and `push()` / `replace()` (path branch).
+  - When the path already contains a `?`, the serialized query is appended with `&`; otherwise with `?`.
+  - Added 6 vitest cases covering: path + query object, URL encoding of keys/values, skipping `null` / `undefined`, merging with a path-embedded query, empty-query no-op, and the equivalent `replace()` case.
+
+- **`onNotFound` was never emitted when a `'*'` catch-all route was configured** — `runRoutingPipeline()` only dispatched `notFound` on the true no-match path (`!ctx.match`). With a `'*'` route present, `regexparam` turned it into a wildcard that matched every unmatched URL, so `ctx.match` was always truthy and the event was suppressed. Apps that configured a `'*': NotFound` route to render a 404 page lost the ability to *observe* 404s programmatically (for logging, analytics, error tracking).
+  - In `src/lib/Router.svelte`, after the no-match early-exit, dispatch `notFound` whenever `ctx.match.routeItem.path === '*'`. The catch-all component still renders — the event is purely additive.
+  - The check uses the same exact-`'*'` test as the existing `isCatchAll` flag at line 727, so subtree wildcards like `'/admin/*'` (whose `routeItem.path` is `/admin/*`, not `*`) and the synthetic unauthorized-route match (whose `routeItem.path` is the unauthorized route) are unaffected.
+  - Added an e2e test in `e2e/router-events.spec.ts` asserting that both the catch-all component renders *and* `onNotFound` fires with the correct `{ location, querystring }` payload. The pre-existing nested-router-without-catch-all test still covers the true no-match path.
+
+### Added
+- **`revalidateCurrentRoute()` + `onRevalidationFailure` — re-check the active route on user state changes** — `hasPermission()` reactivity (above) covers UI element visibility (menus, buttons), but it doesn't cover the case where the user is *sitting on a protected page* when their permissions are revoked. The router checks route conditions only during navigation, so a user already on `/admin` who loses admin permission would stay on `/admin` until they navigated away. This is exactly the websocket-permission-update scenario most real apps need to handle.
+  - New `revalidateCurrentRoute()` export from the main module. Re-runs guards and conditions against the currently mounted route without re-mounting the component. On success, nothing visible happens — the component keeps its state (no flicker, no scroll reset, no in-flight form data lost). On failure, the same unauthorized handling that runs for fresh navigation fires here too.
+  - New `configurePermissions({ onRevalidationFailure })` callback. When configured, fires *instead of* the standard unauthorized handling for revalidation failures — letting apps show a confirmation dialog, soft-warn the user, or log an audit trail before deciding what to do. If the callback doesn't navigate, the user stays on the current page. The `onConditionsFailed` Router event still fires for consistency with navigation behavior. Pass `null` to clear and fall back to standard handling.
+  - Calls to `revalidateCurrentRoute()` within a ~50ms window are coalesced into a single re-validation pass — safe to call on every websocket message.
+  - Multiple Router instances (nested routers, zones) each register independently and re-validate their own routes.
+  - Implementation: `runRoutingPipeline` accepts a `revalidationOnly` option that (a) skips the `beforeLeave` guards (user isn't navigating away), (b) skips the `routeLoading` event dispatch (nothing's loading), (c) on success returns early before the load/commit phases (preserves the mounted component), (d) on failure routes through the new callback when configured. The existing `loadingId` race-condition mechanism handles overlapping navigation/revalidation cleanly.
+  - vitest coverage in `navigation.test.js` (5 new cases: debounce, coalescing, multi-listener, unregister, throwing-listener tolerance) and `permissions.test.js` (4 new cases for the handler getter/setter contract).
+  - e2e: new `RevalidateTest` + `RevalidateProtected` fixtures and `e2e/revalidate.spec.ts` (3 tests: callback fires on protected-route downgrade, no callback when still authorized, no-op on unprotected routes). App.svelte wires up an `onRevalidationFailure` recorder for the spec to assert on.
+  - **Bug fix found while wiring this up:** the pipeline's internal `isPermissionFailure` value is the permissions object (truthy) rather than the literal `true`. Coerced to a boolean before exposing it in the callback's `detail`.
+
+- **`setCurrentUser()` / `getCurrentUser()` — reactivity-by-default for `hasPermission()`** — Previously, `hasPermission()` only re-evaluated in `{#if}` blocks if the consumer's configured `getCurrentUser` happened to read reactive state. The README's canonical example used `getCurrentUser: () => get(currentUser)` (Svelte 4 store, non-reactive read), so following the docs literally meant `{#if hasPermission(...)}` only updated on navigation. A websocket pushing a permission change wouldn't update the UI until the user clicked a link.
+  - Added module-level `$state` (`currentUserState`) inside `permissions.svelte.js`. The default `currentUserGetter` now reads from this rune, so any `hasPermission()` call inside a reactive context (`{#if}`, `$derived`, `$effect`) automatically tracks user changes.
+  - New `setCurrentUser(user)` export — consumers call this on login/logout/websocket update; every reactive `hasPermission()` call site re-evaluates immediately. No subscription wiring needed on the consumer side.
+  - New `getCurrentUser()` export — symmetric reader for cases like `setCurrentUser({ ...getCurrentUser(), permissions: newPerms })`.
+  - `configurePermissions({ getCurrentUser })` still works for consumers who already maintain their own reactive user store (and remains the right choice when they do). Pass `getCurrentUser: null` to explicitly reset back to the default state-backed getter.
+  - **Migration:** existing apps keep working unchanged. New apps can skip `getCurrentUser` and use `setCurrentUser` instead — typically less code and guaranteed-reactive without thinking about it. The README, `permissions.d.ts`, and `ai/permissions.txt` now recommend this path and call out the non-reactive footgun explicitly.
+  - vitest coverage (`src/tests/permissions.test.js`): 5 new cases — `setCurrentUser`/`getCurrentUser` round-trip, `hasPermission` reflecting writes, explicit `getCurrentUser` overriding the default, `getCurrentUser: null` resetting back, and logged-out (`null`) handling.
+
+- **Diagnostic warning when `shouldDisplayLoadingOnRouteLoad` routes never call `hideLoading()`** — Routes configured with `wrap({ shouldDisplayLoadingOnRouteLoad: true, loadingComponent: ... })` mount the real component immediately but keep it hidden under the loading component, waiting for the component itself to call `hideLoading()` from `@keenmate/svelte-spa-router/helpers/route-metadata` once data is ready. Previously, if the consumer forgot to call `hideLoading()` (or threw before reaching it, or hit a code path that didn't call it), the loading screen stayed up forever — no console message, no timeout, no recovery short of navigating away. The author hit this themselves while writing the e2e fixture and spent ten minutes debugging a "broken" wrap option.
+  - `startRouteLoading()` in `route-metadata.svelte.js` now schedules a `setTimeout(console.warn, 10_000)` that fires only if `isRouteLoading` is still true at the threshold. Bypasses the configurable logger (matches the project convention that misconfiguration warnings always print). The message names the option, names the required call, and links to the README.
+  - `hideLoading()` and a subsequent `startRouteLoading()` both clear the timer so the warning never fires when things are working normally.
+  - vitest coverage in `route-metadata.test.js`: three new cases (warning fires after threshold, warning doesn't fire when `hideLoading()` is called in time, warning timer resets on subsequent `startRouteLoading()`).
+
+- **Pending `waitForRouteReady()` promises are resolved when a new navigation starts** — Previously, if a user navigated away from a `shouldDisplayLoadingOnRouteLoad` route before its `hideLoading()` fired, the next `startRouteLoading()` clobbered `routeReadyResolvers = []` without resolving the pending entry. The old pipeline's `await waitForRouteReady()` was orphaned and leaked one unresolvable promise per abandoned navigation. After resolving, it would also have raced with the new pipeline's state writes if not for the new race check.
+  - `startRouteLoading()` now resolves any pending resolvers before clearing the array.
+  - `Router.svelte` adds a `loadingId !== loadingId` race-condition check immediately after `await waitForRouteReady()`, matching the pattern already used after `pipelineLoadComponent` and `pipelineLoadZoneComponents`. Stale pipeline runs bail cleanly instead of racing.
+  - vitest coverage: new case asserting that a second `startRouteLoading()` resolves the first navigation's pending waiter.
+
+- **Documented the `shouldDisplayLoadingOnRouteLoad` contract loudly** — `wrap.d.ts`, `wrap.js`, `routes.d.ts`, `helpers/hierarchy.d.ts`, and the README's Pattern 1 section now spell out the "you MUST call `hideLoading()`" requirement and the blank-page failure mode. Old docstring was 14 words; new copy names the failure mode and the dev-mode safety net.
+
+- **`relativeLocation` field on every Router event payload** — Nested Routers configured with `prefix="/foo/bar"` define their routes in prefix-relative terms (e.g. `'/known'`, not `'/foo/bar/known'`) and match against the prefix-stripped path internally. But every event payload (`onRouteLoading`, `onRouteLoaded`, `onConditionsFailed`, `onNotFound`) reported the **full app URL** in `location` — so the router used two different notions of "location" depending on whether you looked at route definitions or event payloads. Consumers had to know the difference and strip the prefix themselves to reason about what the nested Router actually saw.
+  - Added a new `relativeLocation` field to every dispatched event payload that already carried `location`. For a root Router (no `prefix`), `relativeLocation === location`. For a nested Router with `prefix`, it's the path with the prefix stripped (`/` if stripping leaves it empty). For paths outside the prefix (the rare case where the parent app navigates to something the nested Router doesn't own), `relativeLocation` equals `location`.
+  - `location` is preserved unchanged — useful for logging, analytics, and re-navigating with `push()` (which always takes app-wide paths). `relativeLocation` is useful for reasoning about *this* Router's routing decisions.
+  - All 7 `dispatchNextTick` sites in `Router.svelte` updated. The field is computed once per pipeline run in `createPipelineContext` and threaded through `ctx`.
+  - README event-payload table updated to list the field and explain when it differs from `location`.
+  - e2e coverage: extended `e2e/router-events.spec.ts` to assert (1) `relativeLocation === '/missing'` for a nested Router with `prefix="/test/embed"` navigating to `/test/embed/missing`, and (2) `relativeLocation === location` for the root Router with no prefix.
+
+### Changed (docs)
+- **Documented `conditions` failure behavior and the `conditions` vs `permissions` distinction** — Previously the README showed how to *write* a `wrap({ conditions: [...] })` guard and listed `onConditionsFailed` as a Router event, but never explained what the user actually sees when a condition returns `false`: the route component is unmounted, the slot becomes empty, and no built-in fallback UI is rendered. This surprised even the maintainers when writing the e2e suite — assertions assumed conditions failures would mount the same Unauthorized component that the permission system mounts.
+  - `README.md`: added a "What happens when a condition returns `false`" callout to the *Route guards (pre-conditions)* section; expanded the *Event handling* example with a payload-shape table (`onRouteLoading` / `onRouteLoaded` / `onConditionsFailed` / `onNotFound`); added a new *Conditions vs Permissions* subsection with a side-by-side comparison covering setup, where the logic lives, what happens on failure (UI + event), and when to choose each.
+  - `ai/guards-conditions.txt`: added a `WHAT HAPPENS ON FAILURE` section mirroring the README so the AI-facing summary captures the same fact.
+  - **No code change.** The conditions/permissions split is the intended design — conditions are the low-level primitive, permissions are the opinionated wrapper that builds on top. Per the project's "library shouldn't paint default UI" principle (see the toast removal in this same release), conditions stay unopinionated. The behavior just needed to be documented.
+
+### Removed (breaking — rc02 is unreleased)
+- **Built-in error toast removed from `GlobalErrorHandler`** — The library used to render its own `<div class="error-toast">` on caught errors, gated by the `showToast` config flag (`true` by default). The render condition was `toastVisible && errorState.currentError && !config.showErrorComponent`, which made it dead code under the default `navigateSafe` strategy: that strategy calls `clearError()` synchronously after `push()` in the same handler tick, so by the time Svelte's reactive system flushed the `toastVisible = true` update, `errorState.currentError` was already `null` and the toast never rendered. `restart` with `autoRestart: false` and `showError` set `config.showErrorComponent = true`, which the same guard hides — so the toast was effectively only observable for `restart` with `autoRestart: true` during the delay window, and for `custom` strategies that left state untouched.
+  - Rather than patch the broken interaction, the toast is removed entirely. Notification UI is the consumer's responsibility — every app already has a preferred toast/snackbar library, and the router's job is to surface the event, not paint pixels.
+  - `onError(error, errorInfo, context)` is the supported integration point and was already wired up. Consumers can call their own toast library, Sentry, LogRocket, analytics, etc. from inside that callback.
+  - Removed: `showToast` config field (was: `boolean`, default `true`), `toastVisible` / `toastTimeoutId` state, `showToast()` / `dismissToast()` helpers, the toast `{#if}` block in the template, and all `.error-toast` / `.toast-*` CSS in `GlobalErrorHandler.svelte`.
+  - Updated: the `GlobalErrorHandlerConfig` TypeScript declaration (`error-handler.d.ts`), the example app (`main.js`, `ErrorHandlingDemo.svelte`, `test/ErrorTest.svelte`), and documentation (`README.md`, `ai/error-handling.txt`, `CLAUDE.md`, `e2e/README.md`, `e2e/error-handling.spec.ts`) to drop `showToast` and point at `onError` as the toast hook.
+  - **Migration:** if you were passing `showToast: true`, remove it (TypeScript will flag it). To preserve toast behavior, call your toast library inside `onError` — e.g. `onError: (error) => toast.error(error.message)`.
+
+### Added
+- **Playwright e2e test suite** — Browser-level tests for the router, run against the example app in history mode on port 5050. Dedicated, minimal fixture pages live under `example/src/routes/test/` and are kept separate from the demo routes (which are user-oriented and evolve over time) so assertions stay stable.
+  - **16 specs / 98 tests** covering all 20 feature areas from `ai/INDEX.txt`: basic setup & events, navigation (push/replace/pop/goBack + array/object signatures), named routes, route params (required / optional / wildcard), permissions (RBAC + authorization), guards & conditions, hierarchical inheritance, tree structure (`createHierarchy`), link actions (`use:link`, `use:active`), error handling (GlobalErrorHandler), referrer tracking, breadcrumbs / route metadata, debug logging & `window.components` API, querystring helpers, filters, multi-zone, loading states, 404 / NotFound, `wrap()`, and `routeContext`.
+  - Playwright auto-starts the example dev server and reuses an already-running one (so `make dev` in another terminal is fine).
+  - Each fixture surfaces router state via `data-testid` nodes; action buttons use `data-testid="btn-<action>"`. Reload always resets fixture state.
+  - New npm scripts: `test:e2e`, `test:e2e:install`, `test:e2e:ui`, `test:e2e:headed`. New Makefile targets: `test-e2e`, `test-e2e-install`, `test-e2e-ui`.
+  - Documentation: `e2e/README.md` covers run instructions, the fixture/spec convention, a coverage matrix, and a 6-step recipe for adding new fixtures. A discoverable in-browser index of all fixtures lives at `/test`.
+
 ## [5.2.0-rc01] - 2026-02-18
 
 ### Fixed

package/README.md

@@ -28,6 +28,28 @@ Main features:
 
 This module is released under MIT license.
 
+## What's new
+
+### v5.2.0-rc02
+
+- **Playwright e2e suite** — 16 specs / 103 tests covering every feature area, with dedicated browser-level fixtures in `example/src/routes/test/`
+- **`setCurrentUser()` + reactivity-by-default** — `hasPermission()` updates live in `{#if}` blocks without subscription wiring; no more `get(store)` footgun
+- **`revalidateCurrentRoute()` + `onRevalidationFailure`** — re-check the currently mounted route on out-of-band user changes (websocket permission updates, token refresh) without remounting on success
+- **`relativeLocation` on every Router event payload** — prefix-stripped view for nested routers; `location` stays full URL
+- **Several router fixes** — `push('/path', {}, queryObj)` was dropping the query; `onNotFound` never fired when `'*'` catch-all was configured; `navigationContext()` was leaking the internal `_routeName` key (so `!ctx` was never true)
+- **Diagnostic warning** when `shouldDisplayLoadingOnRouteLoad` routes never call `hideLoading()` — surfaces forgotten-callback bugs after 10s instead of blank pages forever
+- **Built-in toast removed from `GlobalErrorHandler`** (breaking — rc02 unreleased) — notification UI belongs in your stack via the `onError` callback
+
+### v5.2.0-rc01
+
+- **`defineRoutes()`** — type-safe route definitions with IDE autocomplete on route names and params, plus generated `nav.X.push(params)` and `paths.X(params)` helpers
+- **Comprehensive test suite** — expanded from ~156 to 347 passing vitest tests across 16 files (0 skipped)
+- **AI-assistant documentation** — 15 plain-text reference files in `ai/` (basic-setup, navigation, permissions, …) optimized for Claude / Cursor / Copilot
+- **Route Context Demo pages** — interactive examples for `routeContext()`, `routeTitle()`, `routeBreadcrumbs()`
+- **Several TypeScript + correctness fixes** — `routeContext()` mangled name, `wrap()` not merging `title`/`breadcrumbs` into routeContext, missing type declarations for `GlobalErrorHandler` / `ErrorDisplay` / `setHierarchicalRoutesEnabled` / `setIncludeReferrer`
+
+Full details in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Installation
 
 ```sh
@@ -957,6 +979,16 @@ The router provides flexible loading control with support for three distinct pat
 
 Use `loadingComponent` with `shouldDisplayLoadingOnRouteLoad: true` for multi-zone layouts where the Router manages the loading state:
 
+> **⚠️ You must call `hideLoading()` from the route component.** When
+> `shouldDisplayLoadingOnRouteLoad: true` is set, the router mounts the route
+> component immediately but keeps it hidden under `loadingComponent` and waits
+> for an explicit `hideLoading()` signal before revealing it. If the component
+> never calls `hideLoading()` (forgotten, thrown before reaching it, conditional
+> code path that didn't run), the loading screen stays up forever and the real
+> component never appears — the route is effectively bricked until the user
+> navigates away. In development, a `console.warn` fires after 10 seconds to
+> surface this; production has no automatic recovery.
+
 ```javascript
 import { createRoute } from '@keenmate/svelte-spa-router/wrap'
 import { hideLoading } from '@keenmate/svelte-spa-router/helpers/route-metadata'
@@ -1234,6 +1266,25 @@ const routes = {
 }
 ```
 
+**What happens when a condition returns `false`:**
+The route's component is not mounted — the slot becomes **empty**. There is no
+built-in fallback UI. The router fires the `onConditionsFailed` event (see
+[Event handling](#event-handling)) and that's it. The consumer decides what
+happens next, typically by either redirecting from inside the condition itself
+(`await push('/login'); return false`) or by handling the event globally:
+
+```svelte
+<Router
+    {routes}
+    onConditionsFailed={(e) => push('/login')}
+/>
+```
+
+If you want batteries-included Unauthorized-component rendering, use the
+[permission system](#permission-based-routing) instead — see
+[Conditions vs Permissions](#conditions-vs-permissions) for when to reach for
+which.
+
 ### Permission-based routing
 
 svelte-spa-router-5 includes a flexible permission system for role-based access control:
@@ -1241,38 +1292,120 @@ svelte-spa-router-5 includes a flexible permission system for role-based access
 **1. Configure the permission system (in main.js before mounting):**
 
 ```javascript
-import { configurePermissions } from '@keenmate/svelte-spa-router/helpers/permissions'
-import { get } from 'svelte/store'
-import { currentUser } from './stores/auth'
+import {
+    configurePermissions,
+    setCurrentUser
+} from '@keenmate/svelte-spa-router/helpers/permissions'
 
 configurePermissions({
-  checkPermissions: (user, requirements) => {
-    if (!user) return false
-    if (!requirements) return true
-
-    // Check if user has any of the required permissions
-    if (requirements.any) {
-      return requirements.any.some(perm =>
-        user.permissions.includes(perm)
-      )
-    }
+    checkPermissions: (user, requirements) => {
+        if (!user) return false
+        if (!requirements) return true
+
+        // Check if user has any of the required permissions
+        if (requirements.any) {
+            return requirements.any.some(perm => user.permissions.includes(perm))
+        }
 
-    // Check if user has all required permissions
-    if (requirements.all) {
-      return requirements.all.every(perm =>
-        user.permissions.includes(perm)
-      )
+        // Check if user has all required permissions
+        if (requirements.all) {
+            return requirements.all.every(perm => user.permissions.includes(perm))
+        }
+
+        return true
+    },
+    onUnauthorized: (detail) => {
+        push('/unauthorized')
     }
+})
 
-    return true
-  },
-  getCurrentUser: () => get(currentUser),
-  onUnauthorized: (detail) => {
-    push('/unauthorized')
-  }
+// Push the current user into the permission system. The library keeps an
+// internal $state-backed user, so every hasPermission() call site in a
+// reactive context (templates, $derived, $effect) re-evaluates automatically
+// when you call setCurrentUser() again.
+setCurrentUser(null) // logged-out at startup
+
+// Later, on login:
+//   setCurrentUser({ id: 42, permissions: ['admin.read'] })
+// From a websocket permission update:
+//   setCurrentUser({ ...getCurrentUser(), permissions: newPerms })
+// On logout:
+//   setCurrentUser(null)
+```
+
+> **Reactivity:** `hasPermission()` re-evaluates automatically when you call
+> `setCurrentUser()` — the function reads from an internal `$state` rune, so
+> Svelte's tracker registers the dependency in any reactive context (template
+> `{#if}`, `$derived`, `$effect`). No subscription wiring needed on your side.
+>
+> If you maintain your own reactive user store and prefer to read from it
+> directly, pass `getCurrentUser` to `configurePermissions`:
+>
+> ```js
+> configurePermissions({ getCurrentUser: () => myUserState.user, ... })
+> ```
+>
+> Watch out for non-tracked reads (`get(store)`, `localStorage.getItem`, etc.) —
+> those won't propagate updates, and your `{#if hasPermission(...)}` blocks
+> will appear "broken" (only updating on navigation). The default
+> `setCurrentUser`-based path avoids this footgun entirely.
+
+**Re-validating the currently mounted route**
+
+`hasPermission()` reactivity covers UI element visibility — the user's menu
+and buttons update live when permissions change. It does **not** cover the
+case where the user is *sitting on a protected page* when their permissions
+are revoked. The router checks route conditions only during navigation, so a
+user already on `/admin` who loses admin permission stays on `/admin` until
+they navigate away.
+
+To handle this case, call `revalidateCurrentRoute()` after the permission
+change:
+
+```javascript
+import { revalidateCurrentRoute } from '@keenmate/svelte-spa-router'
+import { setCurrentUser, getCurrentUser } from '@keenmate/svelte-spa-router/helpers/permissions'
+
+socket.on('permissions:updated', (newPerms) => {
+    setCurrentUser({ ...getCurrentUser(), permissions: newPerms })
+    revalidateCurrentRoute()
 })
 ```
 
+This re-runs the matched route's guards and conditions against the current
+location. On success, nothing visible happens — the component keeps its
+state (no flicker, no scroll reset, no in-flight form data lost). On
+failure, the same unauthorized handling that runs for fresh navigation
+fires here too.
+
+If you want to customize the failure path — e.g. show a confirmation dialog
+before redirecting, soft-warn the user, log to an audit trail — provide an
+`onRevalidationFailure` handler:
+
+```javascript
+configurePermissions({
+    // ... checkPermissions, etc.
+    onRevalidationFailure: async (detail) => {
+        const confirmed = await showConfirmDialog(
+            'Your permissions have changed. Return to the home page?'
+        )
+        if (confirmed) {
+            push('/')
+        }
+        // If the user dismisses the dialog, they stay on the current page.
+    }
+})
+```
+
+When `onRevalidationFailure` is configured, it fires **instead of** the
+standard unauthorized handling for revalidation failures. The
+`onConditionsFailed` Router event still fires for consistency with normal
+navigation. Pass `onRevalidationFailure: null` to clear and fall back to
+standard handling.
+
+Calls to `revalidateCurrentRoute()` within a ~50ms window are coalesced into
+a single re-validation pass — safe to call on every websocket message.
+
 **2. Protect routes with permissions:**
 
 #### Using createProtectedRoute() (Recommended)
@@ -1408,6 +1541,21 @@ Perfect for:
 
 See `example-permissions/` for a complete working example with mock authentication.
 
+### Conditions vs Permissions
+
+Both gate access to a route, but they have **different defaults** and **different failure paths**. Reach for the one that matches your situation:
+
+| | `wrap({ conditions: [...] })` | `createProtectedRoute({ permissions: ... })` |
+|---|---|---|
+| **What it is** | Low-level primitive: any sync/async predicate(s) you want | Opinionated wrapper around conditions, built on the configured permission system |
+| **Setup needed** | None — just write the function | Call `configurePermissions({ checkPermissions, getCurrentUser, onUnauthorized })` once at app start |
+| **Where the logic lives** | Inline in the condition function | Inside `checkPermissions` (your function), which is reused across every protected route |
+| **On failure: UI** | **Empty slot.** The matched component does not mount; nothing renders in its place unless the consumer redirects | The configured `Unauthorized` component mounts (or `onUnauthorized` callback runs, if set), with `unauthorizedBehavior: 'component' \| 'navigate'` controlling which |
+| **On failure: event** | `onConditionsFailed` fires with `{ route, location, querystring, params }` | Same event fires (permissions are conditions under the hood); the unauthorized handling runs in addition |
+| **When to choose it** | Ad-hoc check that doesn't fit a generic permission model — feature flags, subscription state, ownership of a single resource, custom redirects | Role/permission-based access control where the same `checkPermissions` logic governs many routes and you want a consistent unauthorized UX |
+
+**Common combo:** use `createProtectedRoute` for the role check (gets you the Unauthorized UI) *and* pass extra `conditions` for one-off checks specific to that route. The router runs them in order — permissions first (fast), then your custom conditions.
+
 ### Active link highlighting
 
 ```svelte
@@ -1636,6 +1784,18 @@ await updateQuerystring({ search: null }, { dropNull: false }) // Keeps as ?sear
 
 Prevent navigation when there's unsaved work or other conditions that need user confirmation.
 
+### Which mode should I use?
+
+Three patterns, all calling the same underlying `registerBeforeLeave` primitive — the wrapper and helper are conveniences on top. Pick by ergonomics, not capability.
+
+| Mode | Reach for it when… | Trade-off |
+|---|---|---|
+| **PageWrapper** *(declarative)* | You want a page-level guard tied to the component's lifecycle. Drop the wrapper around your page, write the `beforeLeave` function, done. | Adds one extra component in the markup. Less control over *when* the guard is active during the page's lifetime. |
+| **Direct Registration** *(imperative)* | You need fine control — swap the guard mid-session, toggle it based on a condition, share one guard across multiple components. Call `registerBeforeLeave` / `unregisterBeforeLeave` inside `onMount`/`onDestroy` (or a `$effect`). | You own the lifecycle — easy to forget the cleanup and leak guards across navigations. |
+| **`createDirtyCheckGuard`** *(shortcut)* | Your guard is the classic "form has unsaved changes — confirm before leaving" pattern. The helper bakes in the dirty-check + `confirm()` dialog; just plug in the dirty predicate. | Only fits the dirty-check shape. You still register it the same way as Direct mode — the helper just saves the `confirm` boilerplate. |
+
+> **Tip:** the live demo at `/navigation-guard-demo` (in the example app) lets you switch between all three modes with the same form, so you can compare them side-by-side.
+
 ### Basic Usage with PageWrapper
 
 Create a reusable wrapper component:
@@ -1803,9 +1963,24 @@ const routes = {
     onRouteLoading={(e) => console.log('Loading:', e.detail)}
     onRouteLoaded={(e) => console.log('Loaded:', e.detail)}
     onConditionsFailed={(e) => console.log('Failed:', e.detail)}
+    onNotFound={(e) => console.log('Not found:', e.detail)}
 />
 ```
 
+**Event payloads (`e.detail`):**
+
+| Event | Payload shape | Fires when |
+|---|---|---|
+| `onRouteLoading` | `{ route, location, relativeLocation, querystring, params }` | Before guards/conditions run for a matched route |
+| `onRouteLoaded` | `{ route, location, relativeLocation, querystring, params, component?, name?, routeContext?, zones? }` | After the matched component (and any async children) successfully mounts. `zones` is set for multi-zone routes; `component`/`name`/`routeContext` for single-component routes |
+| `onConditionsFailed` | `{ route, location, relativeLocation, querystring, params }` | A condition in `wrap({ conditions })` returned `false`. The slot is now empty — handle the redirect here or inside the condition itself |
+| `onNotFound` | `{ location, relativeLocation, querystring }` | No route matched, *or* the `'*'` catch-all matched (it fires for both, so consumers can always log 404s) |
+
+**`location` vs `relativeLocation`:**
+- `location` is the **full app URL** as the browser sees it (e.g. `/test/embed/missing`). Use this for logging, analytics, or re-navigating with `push()` (which always takes app-wide paths).
+- `relativeLocation` is the URL **after the Router's `prefix` has been stripped** (e.g. `/missing` for a `<Router prefix="/test/embed" />`). Use this when you're reasoning about what *this* Router instance saw — it matches how routes inside the Router were defined.
+- For a root Router with no `prefix`, the two fields are identical.
+
 ### Tree/Nested Route Structure
 
 Define routes in a hierarchical tree structure as an alternative to flat definitions. Child paths are automatically concatenated to parent paths, and routes inherit metadata from parents.
@@ -2033,6 +2208,9 @@ configureGlobalErrorHandler({
     onError: (error, errorInfo, context) => {
         // Log to Sentry, LogRocket, etc.
         Sentry.captureException(error, { extra: errorInfo })
+
+        // Show a toast/snackbar via your own UI library
+        toast.error(`Something went wrong: ${error.message}`)
     },
 
     strategy: 'navigateSafe', // Navigate to home on error
@@ -2041,7 +2219,6 @@ configureGlobalErrorHandler({
     maxRestarts: 3,
     restartWindow: 60000, // 1 minute
 
-    showToast: true,
     isDevelopment: import.meta.env.DEV
 })
 ```
@@ -2087,8 +2264,8 @@ configureGlobalErrorHandler({
 
 - ✅ Catches ALL errors (render, effect, event handlers, async, promises)
 - ✅ Loop prevention (tracks restarts in sessionStorage)
-- ✅ Toast notifications or full-page error UI
-- ✅ Custom error components
+- ✅ Full-page error UI (default `ErrorDisplay` or your own component)
+- ✅ `onError` callback for wiring up your toast/snackbar library, Sentry, analytics, etc.
 - ✅ Error filtering (ignore known non-critical errors)
 - ✅ TypeScript support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/svelte-spa-router",
-  "version": "5.2.0-rc01",
+  "version": "5.2.0-rc02",
   "description": "Router for SPAs using Svelte 5 with runes, dual-mode routing, permissions, and error handling",
   "main": "./src/lib/index.js",
   "svelte": "./src/lib/Router.svelte",
@@ -97,7 +97,11 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:install": "playwright install chromium",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed"
   },
   "repository": {
     "type": "git",
@@ -124,6 +128,7 @@
     "regexparam": "2.0.2"
   },
   "devDependencies": {
+    "@playwright/test": "^1.48.0",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.2.8",