ui5-lib-guard-router 1.2.0 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Drop-in replacement for `sap.m.routing.Router` that intercepts navigation **before** route matching, target loading, or view creation, preventing flashes of unauthorized content and polluted browser history.
 
-> Born from [SAP/openui5#3411](https://github.com/SAP/openui5/issues/3411), an open request since 2021 for native navigation guard support in UI5.
+> Born from [SAP/openui5#3411](https://github.com/SAP/openui5/issues/3411), an open request for native navigation guard support in UI5.
 >
 > **Related resources**:
 >
@@ -12,6 +12,9 @@ Drop-in replacement for `sap.m.routing.Router` that intercepts navigation **befo
 > [!WARNING]
 > This library is **experimental**. It is not battle-tested in production environments, and the API may change without notice. If you choose to consume it, you do so at your own risk. Make sure to pin your version and review changes before upgrading.
 
+> [!CAUTION]
+> Navigation guards are a UX layer, not a security boundary. They can prevent unauthorized content flashes and steer client-side navigation, but they do **not** replace server-side authorization, backend validation, or service-level access control.
+
 ## Why
 
 UI5's router has no way to block or redirect navigation before views render. The usual workaround, scattering guard logic across `attachPatternMatched` callbacks, causes flashes of unauthorized content, polluted browser history, and scattered guard logic across controllers.
@@ -76,7 +79,7 @@ No transpile tooling, no middleware, no additional `ui5.yaml` changes.
 
 #### Option B: Transpile from source
 
-If you prefer to serve from TypeScript sources (e.g. for debugging with source maps), install [`ui5-tooling-transpile`](https://github.com/nicholasmackey/ui5-tooling-transpile) and enable `transpileDependencies` in your app's `ui5.yaml`:
+If you prefer to serve from TypeScript sources (e.g. for debugging with source maps), install [`ui5-tooling-transpile`](https://github.com/ui5-community/ui5-ecosystem-showcase/tree/main/packages/ui5-tooling-transpile) and enable `transpileDependencies` in your app's `ui5.yaml`:
 
 ```bash
 npm install -D ui5-tooling-transpile
@@ -96,7 +99,7 @@ This transpiles the library's `.ts` sources on the fly during `ui5 serve`.
 
 #### Option C: Static serving (workaround)
 
-If neither option works for your setup, you can mount the pre-built resources manually using [`ui5-middleware-servestatic`](https://github.com/nicholasmackey/ui5-middleware-servestatic) (or a similar community middleware) and point it at the `dist/resources` folder in `node_modules`:
+If neither option works for your setup, you can mount the pre-built resources manually using [`ui5-middleware-servestatic`](https://github.com/ui5-community/ui5-ecosystem-showcase/tree/main/packages/ui5-middleware-servestatic) (or a similar community middleware) and point it at the `dist/resources` folder in `node_modules`:
 
 ```bash
 npm install -D ui5-middleware-servestatic
@@ -171,7 +174,12 @@ export default class Component extends UIComponent {
 
 ## How it works
 
-The library extends [`sap.m.routing.Router`](https://sdk.openui5.org/api/sap.m.routing.Router) and overrides `parse()`, the single method through which all navigation flows (programmatic `navTo`, browser back/forward, direct URL changes). Guards run before any route matching, target loading, or view creation.
+The library extends [`sap.m.routing.Router`](https://sdk.openui5.org/api/sap.m.routing.Router) and intercepts navigation through two entry points:
+
+- **`navTo()` preflight**: For programmatic navigation (`router.navTo()`), guards run _before_ any hash change occurs. If a guard blocks or redirects, the hash never changes, so no history entry is created.
+- **`parse()` fallback**: For browser-initiated navigation (back/forward buttons, URL bar entry, direct hash changes), guards run inside the `parse()` override after the browser has already changed the hash. If a guard blocks or redirects, the router restores the previous hash via `replaceHash()`.
+
+Both entry points feed the same guard pipeline. There is no separate configuration. The same guard functions registered via `addGuard()`, `addRouteGuard()`, and `addLeaveGuard()` protect all navigation paths.
 
 Because it extends the mobile router directly, all existing `sap.m.routing.Router` behavior (Targets, route events, `navTo`, back navigation) works unchanged.
 
@@ -179,7 +187,7 @@ The guard pipeline stays **synchronous when all guards return plain values** and
 
 ## API
 
-All methods return `this` for chaining.
+All guard registration and removal methods return `this` for chaining. `navigationSettled()` returns a `Promise<NavigationResult>`.
 
 ### Guard registration
 
@@ -199,6 +207,10 @@ All methods return `this` for chaining.
 | `removeRouteGuard(routeName, { beforeEnter?, beforeLeave? })` | Remove enter and/or leave guards via object form |
 | `removeLeaveGuard(routeName, fn)`                             | Remove a leave guard                             |
 
+### Unknown routes during registration
+
+`addRouteGuard()` and `addLeaveGuard()` warn when the route name is unknown at registration time, but they still register the guard. This is intentional so applications can attach guards before dynamic `addRoute()` calls or before route definitions are finalized.
+
 ### GuardContext
 
 Every guard receives a `GuardContext` object:
@@ -220,12 +232,12 @@ Enter guards return `GuardResult`, a union of four outcomes:
 GuardResult = boolean | string | GuardRedirect
 ```
 
-| Return                                         | Type            | When to use                                             | Effect                                          |
-| ---------------------------------------------- | --------------- | ------------------------------------------------------- | ----------------------------------------------- |
-| `true`                                         | `boolean`       | Guard condition passes                                  | Allow navigation                                |
-| `false`                                        | `boolean`       | Guard condition fails, no specific destination          | Block (stay on current route, no history entry) |
-| `"routeName"`                                  | `string`        | Redirect to a fixed route (no parameters needed)        | Redirect to named route (replaces history)      |
-| `{ route, parameters?, componentTargetInfo? }` | `GuardRedirect` | Redirect and pass route parameters or component targets | Redirect with parameters (replaces history)     |
+| Return                                         | Type            | When to use                                             | Effect                                                                                                                                                       |
+| ---------------------------------------------- | --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `true`                                         | `boolean`       | Guard condition passes                                  | Allow navigation                                                                                                                                             |
+| `false`                                        | `boolean`       | Guard condition fails, no specific destination          | Stay on current route. Programmatic `navTo()` creates no history entry. Browser-initiated navigation restores the previous hash.                             |
+| `"routeName"`                                  | `string`        | Redirect to a fixed route (no parameters needed)        | Navigate to target route. Programmatic `navTo()` goes directly to target with no intermediate entry. Browser-initiated navigation replaces the current hash. |
+| `{ route, parameters?, componentTargetInfo? }` | `GuardRedirect` | Redirect and pass route parameters or component targets | Same as string redirect, with parameters                                                                                                                     |
 
 `GuardRedirect` is the object form of a redirect. Use it when you need to pass route parameters (`parameters`) or nested component targets (`componentTargetInfo`). For simple redirects without parameters, the string shorthand (`return "home"`) is equivalent and shorter.
 
@@ -260,16 +272,19 @@ import NavigationOutcome from "ui5/guard/router/NavigationOutcome";
 const result: NavigationResult = await router.navigationSettled();
 ```
 
-| `result.status`                | Meaning                                                                      |
-| ------------------------------ | ---------------------------------------------------------------------------- |
-| `NavigationOutcome.Committed`  | Guards allowed the navigation; target route is now active                    |
-| `NavigationOutcome.Blocked`    | A guard blocked navigation; previous route stays active                      |
-| `NavigationOutcome.Redirected` | A guard redirected navigation to a different route                           |
-| `NavigationOutcome.Cancelled`  | Navigation was cancelled before settling (superseded, stopped, or destroyed) |
+| `result.status`                | Meaning                                                                                                 |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `NavigationOutcome.Committed`  | Guards allowed the navigation; target route is now active                                               |
+| `NavigationOutcome.Bypassed`   | Guards allowed the navigation, but no route matched; UI5 continued with `bypassed` / not-found handling |
+| `NavigationOutcome.Blocked`    | A guard blocked navigation; previous route stays active                                                 |
+| `NavigationOutcome.Redirected` | A guard redirected navigation to a different route                                                      |
+| `NavigationOutcome.Cancelled`  | Navigation was cancelled before settling (superseded, stopped, or destroyed)                            |
+
+A guard redirect that fails to trigger a follow-up navigation settles as `Blocked` because no route change commits. A nonexistent route name is the most common cause, and the router logs the target name to help diagnose it.
 
-A guard redirect to a nonexistent route name settles as `Blocked` because no route change commits. The router logs a warning with the bad target name.
+An accepted unmatched hash settles as `Bypassed` with `route === ""` and the attempted hash preserved in `hash`. Idle `navigationSettled()` calls replay that `Bypassed` result until another navigation settles, matching the existing replay behavior for the other outcomes.
 
-If no navigation is in flight, `navigationSettled()` resolves immediately with the most recent settlement result. That makes it safe to call right after `navTo()`, even when guards settle synchronously. On a fresh router (or after `stop()`/`destroy()`), this defaults to `Committed` with the current state. Multiple callers waiting on the same pending navigation all receive the same result.
+If no navigation is in flight, `navigationSettled()` resolves immediately with the most recent settlement result. That makes it safe to call right after `navTo()`, even when guards settle synchronously. On a fresh router, this defaults to `Committed` with the instance's current route/hash state. After `stop()`, those fields are reset, so idle calls resolve with empty strings until the next navigation settles. Multiple callers waiting on the same pending navigation all receive the same result.
 
 **App code: busy indicator during async guards**
 
@@ -290,6 +305,9 @@ const result = await router.navigationSettled();
 switch (result.status) {
 	case NavigationOutcome.Committed:
 		break; // navigation succeeded
+	case NavigationOutcome.Bypassed:
+		MessageToast.show("No route matched; showing not-found flow");
+		break;
 	case NavigationOutcome.Blocked:
 		MessageToast.show("Access denied");
 		break;
@@ -310,6 +328,21 @@ assert.strictEqual(result.status, NavigationOutcome.Blocked, "Navigation was blo
 assert.strictEqual(result.route, "home", "User stays on home");
 ```
 
+**Event-based: observe every navigation outcome**
+
+`attachNavigationSettled` fires synchronously after every guard pipeline settlement. Unlike the one-shot `navigationSettled()` Promise, the event fires for every navigation without re-registration:
+
+```typescript
+router.attachNavigationSettled((event) => {
+	const status = event.getParameter("status"); // NavigationOutcome
+	const route = event.getParameter("route");
+	const hash = event.getParameter("hash");
+	console.log(`Navigation settled: ${status} on ${route}`);
+});
+```
+
+Use `detachNavigationSettled(fnFunction, oListener)` to remove the listener. The same function and listener references must match those passed to `attachNavigationSettled`. The event uses UI5's native `EventProvider` mechanism, so the standard `attachEvent` / `detachEvent` pattern also works.
+
 ### Execution order
 
 1. **Leave guards** for the current route (registration order)
@@ -349,8 +382,12 @@ router.addGuard((context): GuardRedirect | true => {
 });
 ```
 
+The demo app keeps `createRedirectWithParamsGuard()` as a reference implementation in `packages/demo-app/webapp/guards.ts`; the runnable demo routes do not use it because they have no route parameters.
+
 ### Guard factories
 
+The demo app keeps reusable guard factories in `packages/demo-app/webapp/guards.ts`. `createDirtyFormGuard()` is actively registered as a leave guard on the `"protected"` route; `createAuthGuard()` is a reference-only synchronous alternative to the async `createAsyncPermissionGuard()` used by the demo.
+
 ```typescript
 // guards.ts
 import JSONModel from "sap/ui/model/json/JSONModel";
@@ -371,16 +408,18 @@ export function createDirtyFormGuard(formModel: JSONModel): LeaveGuardFn {
 
 ### Object form with RouteGuardConfig
 
+The runnable demo uses the same object form in `packages/demo-app/webapp/Component.ts`, pairing an async permission check with a leave guard on the `protected` route.
+
 ```typescript
 import type { RouteGuardConfig } from "ui5/guard/router/types";
 
-const orderGuards: RouteGuardConfig = {
-	beforeEnter: createAuthGuard(authModel),
+const protectedGuards: RouteGuardConfig = {
+	beforeEnter: createAsyncPermissionGuard(authModel),
 	beforeLeave: createDirtyFormGuard(formModel),
 };
 
-router.addRouteGuard("editOrder", orderGuards);
-// later: router.removeRouteGuard("editOrder", orderGuards);
+router.addRouteGuard("protected", protectedGuards);
+// later: router.removeRouteGuard("protected", protectedGuards);
 ```
 
 ### Dynamic guard registration
@@ -400,25 +439,28 @@ router.removeGuard(logGuard);
 
 ### Leave guard with controller lifecycle
 
+The demo app shows the same lifecycle pattern in `packages/demo-app/webapp/controller/Home.controller.ts`, registering `createHomeLeaveLogger()` on the `home` route and removing it again in `onExit()`.
+
 ```typescript
 import type { GuardRouter, LeaveGuardFn } from "ui5/guard/router/types";
-import { createDirtyFormGuard } from "./guards";
+import BaseController from "./BaseController";
+import { createHomeLeaveLogger } from "../guards";
 
-export default class EditOrderController extends Controller {
-	private _leaveGuard: LeaveGuardFn;
+export default class HomeController extends BaseController {
+	private _leaveGuard: LeaveGuardFn | null = null;
 
 	onInit(): void {
-		const formModel = new JSONModel({ isDirty: false });
-		this.getView()!.setModel(formModel, "form");
-
-		const router = UIComponent.getRouterFor(this) as GuardRouter;
-		this._leaveGuard = createDirtyFormGuard(formModel);
-		router.addLeaveGuard("editOrder", this._leaveGuard);
+		const router = this.getRouter<GuardRouter>();
+		this._leaveGuard = createHomeLeaveLogger();
+		router.addLeaveGuard("home", this._leaveGuard);
 	}
 
 	onExit(): void {
-		const router = UIComponent.getRouterFor(this) as GuardRouter;
-		router.removeLeaveGuard("editOrder", this._leaveGuard);
+		if (this._leaveGuard) {
+			const router = this.getRouter<GuardRouter>();
+			router.removeLeaveGuard("home", this._leaveGuard);
+			this._leaveGuard = null;
+		}
 	}
 }
 ```
@@ -523,31 +565,43 @@ router.addRouteGuard("dashboard", (context) => {
 });
 ```
 
-### URL bar shows target hash during async guards
+### History guarantees differ by navigation source
+
+Programmatic `router.navTo()` calls get clean history: blocked or redirected navigations create no history entry. Browser back/forward and URL bar entry may leave an extra history entry because the browser changes the hash before guards can intercept. The guard still protects the route, but the browser history may contain a duplicate entry that the router repairs via `replaceHash()`.
 
-When a guard returns a Promise (e.g., a `fetch` call to check permissions), the browser's URL bar shows the target hash while the guard is resolving. If the guard ultimately blocks or redirects, the URL reverts. However, there is a brief window where the displayed URL doesn't match the active route.
+### URL bar shows target hash during async guards (browser-initiated only)
 
-This does **not** affect sync guards, which resolve in the same tick as the hash change (the URL flicker is imperceptible).
+For browser-initiated navigation (back/forward, URL bar entry, direct hash changes), the URL bar shows the target hash while an async guard resolves. If the guard blocks or redirects, the URL reverts via `replaceHash()`. There is a brief window where the displayed URL does not match the active route.
 
-**Why the router doesn't handle this**: UI5's `HashChanger` updates the URL and fires `hashChanged` _before_ `parse()` is called. The router cannot prevent the URL change; it can only react to it. Frameworks like Vue Router and Angular Router avoid this by controlling the URL update themselves (calling `history.pushState` only after guards resolve), but UI5's architecture doesn't allow this without intercepting at the HashChanger level, which is globally scoped and fragile.
+This does **not** apply to programmatic `navTo()` calls, where the hash does not change until guards approve. It also does not affect sync guards on the `parse()` path, which resolve in the same tick as the hash change.
+
+**Why the parse() path cannot prevent this**: UI5's `HashChanger` updates the URL and fires `hashChanged` before `parse()` runs. The router cannot prevent the URL change; it can only react to it. Frameworks like Vue Router and Angular Router avoid this by controlling the URL update themselves (calling `history.pushState` only after guards resolve), but UI5's architecture does not allow this without intercepting at the HashChanger level, which is globally scoped and fragile.
 
 ```
-User clicks link / navTo()
-        ↓
-HashChanger updates browser URL    ← URL changes HERE
-        ↓
-HashChanger fires hashChanged
-        ↓
-Router.parse() called              ← guards run HERE
-        ↓
-   ┌────┴────┐
-allowed    blocked
-   ↓          ↓
-views      _restoreHash()
-load       reverts URL
+Browser-initiated navigation (back/forward, URL bar, setHash):
+  HashChanger updates browser URL    ← URL changes HERE
+          ↓
+  HashChanger fires hashChanged
+          ↓
+  Router.parse() called              ← guards run HERE
+          ↓
+     ┌────┴────┐
+  allowed    blocked
+     ↓          ↓
+  views      _restoreHash()
+  load       reverts URL
+
+Programmatic navigation (navTo):
+  navTo() called                     ← guards run HERE
+          ↓
+     ┌────┴────┐
+  allowed    blocked
+     ↓          ↓
+  super.navTo()  return
+  hash changes   (no hash change)
 ```
 
-Show a busy indicator while async guards resolve. This communicates to the user that navigation is in progress, making the URL bar state a non-issue:
+For the `parse()` path, show a busy indicator while async guards resolve. This communicates that navigation is in progress, making the URL bar state a non-issue:
 
 ```typescript
 router.addRouteGuard("dashboard", async (context) => {
@@ -567,12 +621,67 @@ router.addRouteGuard("dashboard", async (context) => {
 
 This follows the same pattern as [TanStack Router's `pendingComponent`](https://tanstack.com/router/latest/docs/framework/react/guide/navigation-blocking#handling-blocked-navigations): the URL reflects the intent while a loading state signals that the navigation hasn't committed yet.
 
+## Debugging and Troubleshooting
+
+### Enabling guard logs
+
+The router logs guard registration errors, pipeline decisions, and async discard events through UI5's `Log` API under the component name `ui5.guard.router.Router`.
+
+Enable debug-level output programmatically:
+
+```typescript
+import Log from "sap/base/Log";
+Log.setLevel(Log.Level.DEBUG, "ui5.guard.router.Router");
+```
+
+Or set the global log level via URL parameter (per-component filtering is only available through the programmatic API above):
+
+```
+?sap-ui-log-level=DEBUG
+```
+
+> **Note**: UI5 1.120+ uses kebab-case URL parameters (`sap-ui-log-level`). Older versions use camelCase (`sap-ui-logLevel`).
+
+### Log reference
+
+| Level   | Message                                                                             | Trigger                                                                                             |
+| ------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| warning | `addGuard called with invalid guard, ignoring`                                      | Non-function passed to `addGuard()`                                                                 |
+| warning | `addRouteGuard called with invalid guard, ignoring`                                 | Non-function `beforeEnter`, `beforeLeave`, or direct guard                                          |
+| info    | `addRouteGuard called with config missing both beforeEnter and beforeLeave`         | Empty `RouteGuardConfig` object (no handlers)                                                       |
+| warning | `addLeaveGuard called with invalid guard, ignoring`                                 | Non-function passed to `addLeaveGuard()`                                                            |
+| warning | `removeGuard called with invalid guard, ignoring`                                   | Non-function passed to `removeGuard()`                                                              |
+| warning | `removeRouteGuard called with invalid guard, ignoring`                              | Non-function passed to `removeRouteGuard()`                                                         |
+| warning | `removeLeaveGuard called with invalid guard, ignoring`                              | Non-function passed to `removeLeaveGuard()`                                                         |
+| warning | `{method} called for unknown route; guard will still register...`                   | Route name not found at registration time                                                           |
+| warning | `Guard returned invalid value, treating as block`                                   | Enter guard returned something other than `true`, `false`, a non-empty string, or a `GuardRedirect` |
+| warning | `Leave guard returned non-boolean value, treating as block`                         | Leave guard returned something other than `true` or `false`                                         |
+| warning | `Guard redirect target "{route}" did not produce a navigation, treating as blocked` | Redirect target did not trigger a follow-up navigation (most commonly an unknown route name)        |
+| error   | `Guard pipeline failed for "{hash}", blocking navigation`                           | Async guard pipeline rejected in `parse()` fallback path                                            |
+| error   | `Async preflight guard failed for route "{route}", blocking navigation`             | Async guard pipeline rejected in `navTo()` preflight path                                           |
+| error   | `Enter guard [{n}] for/on route "{route}" threw, blocking navigation`               | Sync or async enter guard threw an exception                                                        |
+| error   | `Leave guard [{n}] on route "{route}" threw, blocking navigation`                   | Sync or async leave guard threw an exception                                                        |
+| debug   | `Async guard result discarded (superseded by newer navigation)`                     | A newer navigation invalidated the pending async result (`parse()` path)                            |
+| debug   | `Async preflight result discarded (superseded by newer navigation)`                 | A newer navigation invalidated the pending async result (`navTo()` path)                            |
+
+### Common issues
+
+**Guards not running**: Verify the route name passed to `addRouteGuard()` matches the route name in `manifest.json`, not the pattern or target name. If the guard is on a redirect target, it does not run -- see [Redirect targets bypass guards](#redirect-targets-bypass-guards).
+
+**Navigation blocked unexpectedly**: Only a strict `true` return value allows navigation. Returning `undefined`, `null`, or omitting a return statement blocks. Enable debug-level logging to identify which guard blocked.
+
+**Redirect treated as blocked**: The redirect did not trigger a follow-up navigation. Most often the target route name is wrong, but a same-hash no-op can look similar. The router logs the target name so you can verify the route and parameters.
+
+**Async guard result discarded**: A newer navigation started before the async guard resolved. The router uses a generation counter to discard stale results. This is expected behavior during rapid sequential navigations. The debug log confirms when this occurs.
+
+**URL bar shows target hash, then reverts**: This is expected for async guards. The `HashChanger` updates the URL before `parse()` runs. See [URL bar shows target hash during async guards](#url-bar-shows-target-hash-during-async-guards) for the architectural explanation and the busy-indicator pattern.
+
 ## Compatibility
 
 > [!IMPORTANT]
 > **Shipped UI5 baseline: 1.144.0**
 >
-> The published package declares `minUI5Version: 1.144.0`, and the full CI suite runs on that shipped baseline. In addition, CI runs the library QUnit suite against OpenUI5 `1.120.0` as a compatibility lane for the core router implementation. The compatibility baseline is 1.120 because `DataType.registerEnum` (used for the `NavigationOutcome` enum) requires that version. That extra lane does not change the published manifest baseline, but it provides a concrete verification signal for consumers evaluating older runtimes.
+> The published package declares `minUI5Version: 1.144.0`, and the full CI suite runs on that shipped baseline. In addition, CI runs the library QUnit suite against OpenUI5 `1.120.0` as a compatibility lane for the core router implementation. The compatibility baseline is 1.120 because `DataType.registerEnum` (used for the `NavigationOutcome` enum) requires that version. The shipped baseline also carries a vendored OpenUI5 router parity lane for inherited `sap.m.routing.Router` behavior when no guards are active.
 
 If you maintain an app on an older UI5 stack and want to validate locally, run the dedicated compatibility check from the monorepo root:
 
@@ -580,6 +689,12 @@ If you maintain an app on an older UI5 stack and want to validate locally, run t
 npm run test:qunit:compat:120
 ```
 
+The vendored parity tests run as part of the main QUnit suite:
+
+```bash
+npm run test:qunit
+```
+
 ## License
 
 [MIT](LICENSE)

package/dist/.ui5/build-manifest.json

@@ -16,7 +16,7 @@
 	},
 	"buildManifest": {
 		"manifestVersion": "0.2",
-		"timestamp": "2026-03-17T12:41:14.778Z",
+		"timestamp": "2026-03-20T13:27:11.510Z",
 		"versions": {
 			"builderVersion": "4.1.4",
 			"projectVersion": "4.0.13",
@@ -31,7 +31,7 @@
 			"includedTasks": [],
 			"excludedTasks": []
 		},
-		"version": "1.2.0",
+		"version": "1.3.0",
 		"namespace": "ui5/guard/router",
 		"tags": {
 			"/resources/ui5/guard/router/library-dbg.js": {

package/dist/index.d.ts

@@ -12,23 +12,27 @@
 //   - @types/yargs@17.0.35
 //   - @types/ws@8.18.1
 //   - @types/which@2.0.2
+//   - @types/unist@2.0.11
 //   - @types/three@0.125.3
 //   - @types/stack-utils@2.0.3
 //   - @types/sizzle@2.3.10
 //   - @types/sinonjs__fake-timers@8.1.5
+//   - @types/sinon@21.0.0
 //   - @types/shimmer@1.2.0
 //   - @types/qunit@2.5.4
 //   - @types/offscreencanvas@2019.6.4
+//   - @types/npm-package-arg@6.1.4
 //   - @types/normalize-package-data@2.4.4
 //   - @types/node@25.5.0
 //   - @types/mocha@10.0.10
+//   - @types/minimist@1.2.5
 //   - @types/minimatch@3.0.5
 //   - @types/jquery@3.5.13
 //   - @types/istanbul-reports@3.0.4
 //   - @types/istanbul-lib-report@3.0.3
 //   - @types/istanbul-lib-coverage@2.0.6
 //   - @types/qunit@2.19.13
-/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/library.d.ts"/>
 /// <reference path="./resources/ui5/guard/router/NavigationOutcome.d.ts"/>
-/// <reference path="./resources/ui5/guard/router/types.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/library.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/types.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>

package/dist/resources/ui5/guard/router/.library

@@ -2,7 +2,7 @@
 <library xmlns="http://www.sap.com/sap.ui.library.xsd">
 	<name>ui5.guard.router</name>
 	<vendor>Marco</vendor>
-	<version>1.2.0</version>
+	<version>1.3.0</version>
 	<copyright></copyright>
 	<title>UI5 Router extension with async navigation guards</title>
 	<documentation>Extends sap.m.routing.Router with async navigation guards, running before route matching begins.</documentation>

package/dist/resources/ui5/guard/router/NavigationOutcome-dbg.js

@@ -14,6 +14,8 @@ sap.ui.define([], function () {
   const NavigationOutcome = Object.freeze({
     /** Navigation was allowed and the target route activated. */
     Committed: "committed",
+    /** Navigation was allowed, but no route matched; UI5 continued with bypassed handling. */
+    Bypassed: "bypassed",
     /** A guard blocked navigation; the previous route remains active. */
     Blocked: "blocked",
     /** A guard redirected navigation to a different route. */

package/dist/resources/ui5/guard/router/NavigationOutcome-dbg.js.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationOutcome-dbg.js","names":["NavigationOutcome","Object","freeze","Committed","Blocked","Redirected","Cancelled"],"sources":["NavigationOutcome.ts"],"sourcesContent":["/**\n * Outcome of a navigation after the guard pipeline settles.\n *\n * Registered as a UI5 enum via `library.ts` so that it is discoverable\n * through `sap.ui.base.DataType.getType()`. Application code can import\n * the value object directly.\n *\n * @enum {string}\n * @namespace ui5.guard.router\n */\nconst NavigationOutcome = Object.freeze({\n\t/** Navigation was allowed and the target route activated. */\n\tCommitted: \"committed\" as const,\n\t/** A guard blocked navigation; the previous route remains active. */\n\tBlocked: \"blocked\" as const,\n\t/** A guard redirected navigation to a different route. */\n\tRedirected: \"redirected\" as const,\n\t/** Navigation was cancelled before settling (superseded, stopped, or destroyed). */\n\tCancelled: \"cancelled\" as const,\n});\n\ntype NavigationOutcome = (typeof NavigationOutcome)[keyof typeof NavigationOutcome];\n\nexport default NavigationOutcome;\n"],"mappings":";;;EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACA,MAAMA,iBAAiB,GAAGC,MAAM,CAACC,MAAM,CAAC;IACvC;IACAC,SAAS,EAAE,WAAoB;IAC/B;IACAC,OAAO,EAAE,SAAkB;IAC3B;IACAC,UAAU,EAAE,YAAqB;IACjC;IACAC,SAAS,EAAE;EACZ,CAAC,CAAC;EAAC,OAIYN,iBAAiB;AAAA","ignoreList":[]}
+{"version":3,"file":"NavigationOutcome-dbg.js","names":["NavigationOutcome","Object","freeze","Committed","Bypassed","Blocked","Redirected","Cancelled"],"sources":["NavigationOutcome.ts"],"sourcesContent":["/**\n * Outcome of a navigation after the guard pipeline settles.\n *\n * Registered as a UI5 enum via `library.ts` so that it is discoverable\n * through `sap.ui.base.DataType.getType()`. Application code can import\n * the value object directly.\n *\n * @enum {string}\n * @namespace ui5.guard.router\n */\nconst NavigationOutcome = Object.freeze({\n\t/** Navigation was allowed and the target route activated. */\n\tCommitted: \"committed\",\n\t/** Navigation was allowed, but no route matched; UI5 continued with bypassed handling. */\n\tBypassed: \"bypassed\",\n\t/** A guard blocked navigation; the previous route remains active. */\n\tBlocked: \"blocked\",\n\t/** A guard redirected navigation to a different route. */\n\tRedirected: \"redirected\",\n\t/** Navigation was cancelled before settling (superseded, stopped, or destroyed). */\n\tCancelled: \"cancelled\",\n});\n\ntype NavigationOutcome = (typeof NavigationOutcome)[keyof typeof NavigationOutcome];\n\nexport default NavigationOutcome;\n"],"mappings":";;;EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACA,MAAMA,iBAAiB,GAAGC,MAAM,CAACC,MAAM,CAAC;IACvC;IACAC,SAAS,EAAE,WAAW;IACtB;IACAC,QAAQ,EAAE,UAAU;IACpB;IACAC,OAAO,EAAE,SAAS;IAClB;IACAC,UAAU,EAAE,YAAY;IACxB;IACAC,SAAS,EAAE;EACZ,CAAC,CAAC;EAAC,OAIYP,iBAAiB;AAAA","ignoreList":[]}

package/dist/resources/ui5/guard/router/NavigationOutcome.d.ts

@@ -12,6 +12,8 @@ declare module "ui5/guard/router/NavigationOutcome" {
     const NavigationOutcome: Readonly<{
         /** Navigation was allowed and the target route activated. */
         Committed: "committed";
+        /** Navigation was allowed, but no route matched; UI5 continued with bypassed handling. */
+        Bypassed: "bypassed";
         /** A guard blocked navigation; the previous route remains active. */
         Blocked: "blocked";
         /** A guard redirected navigation to a different route. */

package/dist/resources/ui5/guard/router/NavigationOutcome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationOutcome.d.ts","sourceRoot":"../../../../..","sources":["src/NavigationOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,oCAAoC,CAAC;IACpD;;;;;;;;;OASG;IACH,MAAM,iBAAiB;QACtB,6DAA6D;;QAE7D,qEAAqE;;QAErE,0DAA0D;;QAE1D,oFAAoF;;MAEnF,CAAC;IAEH,KAAK,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;IAEpF,eAAe,iBAAiB,CAAC;CAEhC"}
+{"version":3,"file":"NavigationOutcome.d.ts","sourceRoot":"../../../../..","sources":["src/NavigationOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,oCAAoC,CAAC;IACpD;;;;;;;;;OASG;IACH,MAAM,iBAAiB;QACtB,6DAA6D;;QAE7D,0FAA0F;;QAE1F,qEAAqE;;QAErE,0DAA0D;;QAE1D,oFAAoF;;MAEnF,CAAC;IAEH,KAAK,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;IAEpF,eAAe,iBAAiB,CAAC;CAEhC"}

package/dist/resources/ui5/guard/router/NavigationOutcome.js

@@ -1,2 +1,2 @@
-sap.ui.define([],function(){"use strict";const e=Object.freeze({Committed:"committed",Blocked:"blocked",Redirected:"redirected",Cancelled:"cancelled"});return e});
+sap.ui.define([],function(){"use strict";const e=Object.freeze({Committed:"committed",Bypassed:"bypassed",Blocked:"blocked",Redirected:"redirected",Cancelled:"cancelled"});return e});
 //# sourceMappingURL=NavigationOutcome.js.map

package/dist/resources/ui5/guard/router/NavigationOutcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationOutcome.js","names":["NavigationOutcome","Object","freeze","Committed","Blocked","Redirected","Cancelled"],"sources":["NavigationOutcome.ts"],"sourcesContent":["/**\n * Outcome of a navigation after the guard pipeline settles.\n *\n * Registered as a UI5 enum via `library.ts` so that it is discoverable\n * through `sap.ui.base.DataType.getType()`. Application code can import\n * the value object directly.\n *\n * @enum {string}\n * @namespace ui5.guard.router\n */\nconst NavigationOutcome = Object.freeze({\n\t/** Navigation was allowed and the target route activated. */\n\tCommitted: \"committed\" as const,\n\t/** A guard blocked navigation; the previous route remains active. */\n\tBlocked: \"blocked\" as const,\n\t/** A guard redirected navigation to a different route. */\n\tRedirected: \"redirected\" as const,\n\t/** Navigation was cancelled before settling (superseded, stopped, or destroyed). */\n\tCancelled: \"cancelled\" as const,\n});\n\ntype NavigationOutcome = (typeof NavigationOutcome)[keyof typeof NavigationOutcome];\n\nexport default NavigationOutcome;\n"],"mappings":"yCAUA,MAAMA,EAAoBC,OAAOC,OAAO,CAEvCC,UAAW,YAEXC,QAAS,UAETC,WAAY,aAEZC,UAAW,cACT,OAIYN,CAAiB","ignoreList":[]}
+{"version":3,"file":"NavigationOutcome.js","names":["NavigationOutcome","Object","freeze","Committed","Bypassed","Blocked","Redirected","Cancelled"],"sources":["NavigationOutcome.ts"],"sourcesContent":["/**\n * Outcome of a navigation after the guard pipeline settles.\n *\n * Registered as a UI5 enum via `library.ts` so that it is discoverable\n * through `sap.ui.base.DataType.getType()`. Application code can import\n * the value object directly.\n *\n * @enum {string}\n * @namespace ui5.guard.router\n */\nconst NavigationOutcome = Object.freeze({\n\t/** Navigation was allowed and the target route activated. */\n\tCommitted: \"committed\",\n\t/** Navigation was allowed, but no route matched; UI5 continued with bypassed handling. */\n\tBypassed: \"bypassed\",\n\t/** A guard blocked navigation; the previous route remains active. */\n\tBlocked: \"blocked\",\n\t/** A guard redirected navigation to a different route. */\n\tRedirected: \"redirected\",\n\t/** Navigation was cancelled before settling (superseded, stopped, or destroyed). */\n\tCancelled: \"cancelled\",\n});\n\ntype NavigationOutcome = (typeof NavigationOutcome)[keyof typeof NavigationOutcome];\n\nexport default NavigationOutcome;\n"],"mappings":"yCAUA,MAAMA,EAAoBC,OAAOC,OAAO,CAEvCC,UAAW,YAEXC,SAAU,WAEVC,QAAS,UAETC,WAAY,aAEZC,UAAW,cACT,OAIYP,CAAiB","ignoreList":[]}