@nutin/cli 2.1.0 → 3.0.0

package/templates/base/src/core/services/router/helpers/navigation-manager.helper.test.js.hbs

@@ -1,8 +1,30 @@
-import { NavigationManager } from '#root/dist/src/core/services/router/helpers/navigation-manager.helper.js';
+import * as NavigationManager from '#root/dist/src/core/services/router/helpers/navigation-manager.helper.js';
 import { I18nService } from '#root/dist/src/core/services/index.js';
 import { CONFIG } from '#root/dist/src/core/config.js';
 
+// The announcer's delay, run on fake timers.
+const ANNOUNCE_DELAY = 100;
+
+// A view element inside a <main>, both in the document.
+function mountView(html) {
+  const main = document.createElement('main');
+  const element = document.createElement('div');
+  element.innerHTML = html;
+  main.appendChild(element);
+  document.body.appendChild(main);
+  return { view: { viewName: 'probe', getElement: () => element }, main, element };
+}
+
+function cleanupFocusView() {
+  document.querySelectorAll('main, [data-nutin-announcer]').forEach((el) => el.remove());
+}
+
 describe('NavigationManager', () => {
+  afterEach(() => {
+    useRealTimers();
+    cleanupFocusView();
+  });
+
   it('should normalize paths by removing trailing slashes', () => {
     expect(NavigationManager.normalizePath('/about/')).toBe('/about');
     expect(NavigationManager.normalizePath('/about///')).toBe('/about');
@@ -10,6 +32,12 @@ describe('NavigationManager', () => {
     expect(NavigationManager.normalizePath('')).toBe('/');
   });
 
+  it('never returns a path that starts with "//" (another host)', () => {
+    expect(NavigationManager.normalizePath('/./\\evil.example')).toBe('/evil.example');
+    expect(NavigationManager.normalizePath('/a/..\\/evil.example')).toBe('/evil.example');
+    expect(NavigationManager.normalizePath('/%2e/\\evil.example/x')).toBe('/evil.example/x');
+  });
+
   it('should call pushState when conditions are met', () => {
     const originalPushState = window.history.pushState;
     let called = false;
@@ -19,13 +47,13 @@ describe('NavigationManager', () => {
       expect(url).toBe('/about');
     };
 
-    NavigationManager.updateHistory('/about', '/home', true);
+    NavigationManager.updateHistory('/about', '/home', 'push');
     expect(called).toBe(true);
 
     window.history.pushState = originalPushState;
   });
 
-  it('should not call pushState if shouldPushState returns false', () => {
+  it("should not touch history in 'none' mode", () => {
     const originalPushState = window.history.pushState;
     let called = false;
 
@@ -33,12 +61,67 @@ describe('NavigationManager', () => {
       called = true;
     };
 
-    NavigationManager.updateHistory('/about', '/home', false);
+    NavigationManager.updateHistory('/about', '/home', 'none');
 
     expect(called).toBe(false);
     window.history.pushState = originalPushState;
   });
 
+  it("updateHistory in 'replace' mode rewrites the current entry instead of pushing", () => {
+    const originalReplaceState = window.history.replaceState;
+    const originalPushState = window.history.pushState;
+    let pushCalled = false;
+    let replacedUrl = null;
+
+    window.history.pushState = function () {
+      pushCalled = true;
+    };
+    window.history.replaceState = function (state, title, url) {
+      replacedUrl = url;
+    };
+
+    NavigationManager.updateHistory('/about', '/home', 'replace', 'team');
+
+    window.history.pushState = originalPushState;
+    window.history.replaceState = originalReplaceState;
+    expect(pushCalled).toBe(false);
+    expect(replacedUrl).toBe('/about#team');
+  });
+
+  it('replaceState calls history.replaceState (not pushState) with the locale-prefixed path', () => {
+    const originalReplaceState = window.history.replaceState;
+    const originalPushState = window.history.pushState;
+    let pushCalled = false;
+    let replaceArgs = null;
+
+    window.history.pushState = () => { pushCalled = true; };
+    window.history.replaceState = (state, title, url) => { replaceArgs = url; };
+
+    try {
+      NavigationManager.replaceState('/section/first-page');
+      expect(replaceArgs).toBe('/section/first-page');
+      expect(pushCalled).toBe(false);
+    } finally {
+      window.history.replaceState = originalReplaceState;
+      window.history.pushState = originalPushState;
+    }
+  });
+
+  it('replaceState preserves an existing hash fragment', () => {
+    const originalReplaceState = window.history.replaceState;
+    window.history.pushState({}, '', '/section#some-heading');
+    let replaceArgs = null;
+    window.history.replaceState = (state, title, url) => { replaceArgs = url; };
+
+    try {
+      NavigationManager.replaceState('/section/first-page');
+      expect(replaceArgs).toBe('/section/first-page#some-heading');
+    } finally {
+      window.history.replaceState = originalReplaceState;
+      window.history.pushState({}, '', '/');
+    }
+  });
+
   it('should return current path from location', () => {
     // This test assumes a DOM-like environment
     const currentPath = window.location.pathname;
@@ -188,10 +271,47 @@ describe('NavigationManager', () => {
       .toEqual({ postId: '1', commentId: '2' });
   });
 
+  it('matchPattern decodes params and keeps a malformed escape as-is', () => {
+    expect(NavigationManager.matchPattern('/users/:name', '/users/J%C3%B6rg')).toEqual({ name: 'Jörg' });
+    expect(NavigationManager.matchPattern('/users/:name', '/users/100%')).toEqual({ name: '100%' });
+  });
+
+  it('matchPattern matches static segments literally', () => {
+    expect(NavigationManager.matchPattern('/files/report.pdf', '/files/report.pdf')).toEqual({});
+    expect(NavigationManager.matchPattern('/files/report.pdf', '/files/reportXpdf')).toBe(null);
+    expect(NavigationManager.matchPattern('/v1.0/:id', '/v1.0/7')).toEqual({ id: '7' });
+  });
+
+  it('updateHistory keeps the query string', () => {
+    const originalPushState = window.history.pushState;
+    let pushedUrl = null;
+    window.history.pushState = function (state, title, url) {
+      pushedUrl = url;
+    };
+
+    NavigationManager.updateHistory('/list', '/home', 'push', 'top', '?page=2');
+
+    window.history.pushState = originalPushState;
+    expect(pushedUrl).toBe('/list?page=2#top');
+  });
+
   it('matchPattern returns null when the path does not match the pattern at all', () => {
     expect(NavigationManager.matchPattern('/posts/:id', '/other/123')).toBe(null);
   });
 
+  it('updateDocumentTitle prefers the view\'s own documentTitle() over seo.json and viewName', () => {
+    CONFIG.generateSEOFiles = true;
+    CONFIG.seo = { routes: [{ path: '/docs/:slug?', title: 'Docs' }] };
+    try {
+      NavigationManager.updateDocumentTitle({ viewName: 'docs', documentTitle: () => 'How do I navigate?' }, '/docs/:slug?');
+      expect(document.title).toBe('How do I navigate?');
+      NavigationManager.updateDocumentTitle({ viewName: 'docs', documentTitle: () => undefined }, '/docs/:slug?');
+      expect(document.title).toBe('Docs');
+    } finally {
+      CONFIG.generateSEOFiles = false;
+    }
+  });
+
   it('updateDocumentTitle falls back to the view\'s viewName when generateSEOFiles is disabled', () => {
     CONFIG.generateSEOFiles = false;
     CONFIG.seo = { routes: [{ path: '/', title: 'Should not be used' }] };
@@ -226,6 +346,7 @@ describe('NavigationManager', () => {
   });
 
   it('updateDocumentTitle resolves a per-language seo.json title to the current language', () => {
+    CONFIG.i18n = true;
     CONFIG.generateSEOFiles = true;
     CONFIG.seo = { routes: [{ path: '/', title: { en: 'Home', fr: 'Accueil' } }] };
     I18nService['_LANGUAGES'] = ['en', 'fr'];
@@ -234,12 +355,26 @@ describe('NavigationManager', () => {
       NavigationManager.updateDocumentTitle({ viewName: 'home' }, '/');
       expect(document.title).toBe('Accueil');
     } finally {
+      CONFIG.i18n = false;
       CONFIG.generateSEOFiles = false;
       I18nService['_currentLanguage'] = 'en';
     }
   });
 
+  it('updateDocumentTitle uses the first value of a per-language seo.json title when i18n is disabled', () => {
+    CONFIG.generateSEOFiles = true;
+    CONFIG.seo = { routes: [{ path: '/', title: { fr: 'Accueil', en: 'Home' } }] };
+    I18nService['_currentLanguage'] = 'en';
+    try {
+      NavigationManager.updateDocumentTitle({ viewName: 'home' }, '/');
+      expect(document.title).toBe('Accueil');
+    } finally {
+      CONFIG.generateSEOFiles = false;
+    }
+  });
+
   it('updateDocumentTitle falls back to the default language, then any available language, then viewName', () => {
+    CONFIG.i18n = true;
     CONFIG.generateSEOFiles = true;
     I18nService['_LANGUAGES'] = ['en', 'fr'];
 
@@ -255,6 +390,7 @@ describe('NavigationManager', () => {
       NavigationManager.updateDocumentTitle({ viewName: 'home' }, '/');
       expect(document.title).toBe('home');
     } finally {
+      CONFIG.i18n = false;
       CONFIG.generateSEOFiles = false;
       I18nService['_currentLanguage'] = 'en';
     }
@@ -299,4 +435,81 @@ describe('NavigationManager', () => {
       I18nService['_translations'] = {};
     }
   });
+
+  it('focuses the view\'s h1, made focusable with tabindex="-1"', () => {
+    const { view, element } = mountView('<p>intro</p><h1>Title</h1>');
+    NavigationManager.focusView(view);
+    const h1 = element.querySelector('h1');
+    expect(document.activeElement).toBe(h1);
+    expect(h1.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('keeps an h1\'s own tabindex and styling', () => {
+    const { view, element } = mountView('<h1 tabindex="0">Title</h1>');
+    const h1 = element.querySelector('h1');
+    NavigationManager.focusView(view);
+    expect(h1.getAttribute('tabindex')).toBe('0');
+    expect(h1.style.outline).toBe('');
+    expect(document.activeElement).toBe(h1);
+  });
+
+  it('hides the focus ring of an element it made focusable, and restores it on blur', () => {
+    const { view, element } = mountView('<h1 style="color: red">Title</h1>');
+    const h1 = element.querySelector('h1');
+    NavigationManager.focusView(view);
+    expect(h1.style.outline).toBe('none');
+
+    h1.blur();
+    expect(h1.hasAttribute('tabindex')).toBe(false);
+    expect(h1.style.outline).toBe('');
+    expect(h1.getAttribute('style')).toBe('color: red;');
+  });
+
+  it('leaves no style attribute behind on an element that had none', () => {
+    const { view, element } = mountView('<h1>Title</h1>');
+    const h1 = element.querySelector('h1');
+    NavigationManager.focusView(view);
+    h1.blur();
+    expect(h1.hasAttribute('style')).toBe(false);
+  });
+
+  it('falls back to the h1 in <main> when the view has none', () => {
+    const { view, main } = mountView('<p>no heading</p>');
+    const h1 = document.createElement('h1');
+    h1.textContent = 'Layout title';
+    main.prepend(h1);
+    NavigationManager.focusView(view);
+    expect(document.activeElement).toBe(h1);
+  });
+
+  it('focuses the view itself and announces document.title when there is no h1', () => {
+    useFakeTimers();
+    const { view, element } = mountView('<p>no heading</p>');
+    document.title = 'Probe page';
+    NavigationManager.focusView(view);
+    expect(document.activeElement).toBe(element);
+    expect(element.getAttribute('tabindex')).toBe('-1');
+
+    const region = document.querySelector('[data-nutin-announcer]');
+    expect(region.getAttribute('role')).toBe('status');
+    expect(region.getAttribute('aria-live')).toBe('polite');
+    advanceTimersByTime(ANNOUNCE_DELAY - 1);
+    expect(region.textContent).toBe('');
+    advanceTimersByTime(1);
+    expect(region.textContent).toBe('Probe page');
+  });
+
+  it('reuses one announcer, emptying it first so the same title is announced again', () => {
+    useFakeTimers();
+    const { view } = mountView('<p>no heading</p>');
+    document.title = 'Same';
+    NavigationManager.focusView(view);
+    advanceTimersByTime(ANNOUNCE_DELAY);
+    NavigationManager.focusView(view);
+    const regions = document.querySelectorAll('[data-nutin-announcer]');
+    expect(regions.length).toBe(1);
+    expect(regions[0].textContent).toBe('');
+    advanceTimersByTime(ANNOUNCE_DELAY);
+    expect(regions[0].textContent).toBe('Same');
+  });
 });

package/templates/base/src/core/services/router/helpers/navigation-manager.helper.ts.hbs

@@ -1,106 +1,251 @@
-import { I18nService, View } from "../../../index.js";
-import { Language } from "../../i18n/languages.js";
+import type { View } from "../../../base-classes/view/view.js";
+import { I18nService } from "../../i18n/i18n.js";
 import { CONFIG } from "../../../config.js";
 
+// How a navigation affects the history stack: add an entry, rewrite the current one,
+// or leave it untouched (back/forward, reload).
+export type HistoryMode = 'push' | 'replace' | 'none';
+
+// Long enough for screen readers to notice the live region's content change.
+const ANNOUNCE_DELAY = 100;
+
+// See recoverFromFailedViewLoad().
+const RELOAD_KEY = 'nutin:failed-view-load';
+const RELOAD_WINDOW = 10_000;
+
 /**
  * Navigation - handles path normalization and history management
  */
-export class NavigationManager {
-  public static extractLocale(path: string): { locale: Language | null; strippedPath: string } {
-    if (!CONFIG.i18n) return { locale: null, strippedPath: path };
-
+// The i18n guards wrap their branch rather than returning early: esbuild only drops
+// a constant-false block, not code after a constant early return, and I18nService
+// must go unreferenced for prod builds to drop it when i18n is off.
+export function extractLocale(path: string): { locale: Nutin.Language | null; strippedPath: string } {
+  if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
     const segments = path.split('/').filter(Boolean);
-    const first = segments[0] as Language;
+    const first = segments[0] as Nutin.Language;
     if (first && I18nService.languages.includes(first)) {
       const rest = segments.slice(1).join('/');
       return { locale: first, strippedPath: rest ? `/${rest}` : '/' };
     }
-    return { locale: null, strippedPath: path };
   }
+  return { locale: null, strippedPath: path };
+}
 
-  public static addLocalePrefix(strippedPath: string): string {
-    if (!CONFIG.i18n) return strippedPath;
-
+export function addLocalePrefix(strippedPath: string): string {
+  if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
     const lang = I18nService.currentLanguage;
     return strippedPath === '/' ? `/${lang}` : `/${lang}${strippedPath}`;
   }
+  return strippedPath;
+}
 
-  public static getCurrentLocale(): Language | null {
-    return this.extractLocale(window.location.pathname).locale;
+export function getCurrentLocale(): Nutin.Language | null {
+  return extractLocale(window.location.pathname).locale;
+}
+
+export function updateLocaleInUrl(): void {
+  const rawPathname = (new URL(window.location.pathname, window.location.origin).pathname || '/').replace(/\/+$/, '') || '/';
+  const { strippedPath } = extractLocale(rawPathname);
+  const newUrl = addLocalePrefix(strippedPath);
+  if (newUrl !== window.location.pathname) {
+    window.history.pushState({}, '', newUrl + window.location.search + window.location.hash);
   }
+}
 
-  public static updateLocaleInUrl(): void {
-    const rawPathname = (new URL(window.location.pathname, window.location.origin).pathname || '/').replace(/\/+$/, '') || '/';
-    const { strippedPath } = this.extractLocale(rawPathname);
-    const newUrl = this.addLocalePrefix(strippedPath);
-    if (newUrl !== window.location.pathname) {
-      window.history.pushState({}, '', newUrl);
-    }
+export function normalizePath(path: string): string {
+  const collapsed = path.replace(/\/\/+/g, '/');
+  const url = new URL(collapsed, window.location.origin);
+  // Parsing can bring "//" back ("/./\\host" -> "//host"), which the browser reads as another
+  // host (pushState throws, a full page load leaves the site): collapse again.
+  const pathname = (url.pathname || '/').replace(/\/\/+/g, '/').replace(/\/+$/, '') || '/';
+  return extractLocale(pathname).strippedPath;
+}
+
+export function updateHistory(
+  normalizedPath: string,
+  currentPath: string,
+  mode: HistoryMode,
+  hash?: string,
+  search: string = ''
+): void {
+  if (mode === 'none') return;
+  const localizedPath = localizedUrl(normalizedPath, search, hash);
+  const currentUrl = window.location.pathname + window.location.search + window.location.hash;
+  if (currentUrl === localizedPath) return;
+  if (mode === 'push') {
+    window.history.pushState({}, '', localizedPath);
+  } else {
+    window.history.replaceState({}, '', localizedPath);
   }
+}
+
+// The URL of a path as it appears in the address bar: locale prefix, query and hash.
+export function localizedUrl(normalizedPath: string, search: string = '', hash?: string): string {
+  return addLocalePrefix(normalizedPath) + search + (hash ? `#${hash}` : '');
+}
 
-  public static normalizePath(path: string): string {
-    const collapsed = path.replace(/\/\/+/g, '/');
-    const url = new URL(collapsed, window.location.origin);
-    const pathname = (url.pathname || '/').replace(/\/+$/, '') || '/';
-    return this.extractLocale(pathname).strippedPath;
+// A lazy route's view failed to load: usually a deploy replaced the chunks while this tab
+// was open, or the network dropped. A full page load of the target URL fetches the new
+// build. It happens once per URL within RELOAD_WINDOW (recorded in sessionStorage), so a
+// view that keeps failing (or a broken chunk) can't reload forever: the error is logged
+// and the current page stays. Without sessionStorage, it only logs.
+export function recoverFromFailedViewLoad(url: string, error: unknown): void {
+  console.error(`[router] Failed to load the view for "${url}".`, error);
+  try {
+    const last = JSON.parse(sessionStorage.getItem(RELOAD_KEY) ?? 'null') as { url?: string; at?: number } | null;
+    const now = Date.now();
+    if (last?.url === url && typeof last.at === 'number' && now - last.at < RELOAD_WINDOW) return;
+    sessionStorage.setItem(RELOAD_KEY, JSON.stringify({ url, at: now }));
+  } catch {
+    return;
   }
+  loadPage(url);
+}
 
-  public static updateHistory(
-    normalizedPath: string,
-    currentPath: string,
-    pushState: boolean
-  ): void {
-    const localizedPath = this.addLocalePrefix(normalizedPath);
-    if (pushState && window.location.pathname !== localizedPath) {
-      window.history.pushState({}, '', localizedPath);
-    }
+// A full (non-SPA) page load.
+export function loadPage(url: string): void {
+  window.location.assign(url);
+}
+
+// Rewrites the current history entry's URL to match content already rendered
+// (e.g. a route that fell back to a default sub-page) without adding a
+// new back/forward-navigable entry.
+export function replaceState(path: string): void {
+  const localizedPath = addLocalePrefix(path) + window.location.hash;
+  window.history.replaceState({}, '', localizedPath);
+}
+
+// Scrolls to the element matching `hash` (a bare fragment, no leading "#") if it
+// exists; falls back to the top of the page otherwise (no hash, or a stale/broken
+// id) — matches the browser's own native fallback for an unresolvable fragment.
+export function scrollToHash(hash?: string): void {
+  const target = hash ? document.getElementById(hash) : null;
+  if (target) {
+    target.scrollIntoView({ block: 'start' });
+  } else {
+    window.scrollTo({ top: 0 });
+  }
+}
+
+// Moves focus to the new view after an in-app navigation, so keyboard and screen-reader
+// users land on it instead of on <body> (the link they used is gone): its <h1>, else the
+// <h1> in <main>; without one, the view itself, with the page title announced instead.
+// preventScroll keeps scrollToHash()'s position.
+export function focusView(view: View): void {
+  const viewElement = view.getElement();
+  const heading = viewElement.querySelector('h1') ?? document.querySelector('main h1');
+  if (heading instanceof HTMLElement) {
+    focusElement(heading);
+    return;
   }
+  focusElement(viewElement);
+  announce(document.title);
+}
 
-  public static getCurrentPath(): string {
-    return this.normalizePath(window.location.pathname);
+// An element made focusable only for this (a heading, the view) gets no focus ring: it isn't
+// interactive, so the ring would only look like a stray highlight. Screen readers still read it
+// and Tab still continues from it. Once it loses focus, it's restored as it was, so it never
+// becomes a click/Tab target. An element with its own tabindex keeps its own styling.
+function focusElement(element: HTMLElement): void {
+  if (!element.hasAttribute('tabindex')) {
+    const previousOutline = element.style.outline;
+    element.setAttribute('tabindex', '-1');
+    element.style.outline = 'none';
+    element.addEventListener('blur', () => {
+      element.removeAttribute('tabindex');
+      element.style.outline = previousOutline;
+      if (!element.getAttribute('style')) element.removeAttribute('style');
+    }, { once: true });
   }
+  element.focus({ preventScroll: true });
+}
 
-  public static updateDocumentTitle(view: View, pattern: string): void {
-    const route = CONFIG.generateSEOFiles
-      ? CONFIG.seo?.routes?.find((r) => r.path === pattern)
-      : undefined;
-    const seoTitle = route?.title ? this.resolveSeoTitle(route.title) : undefined;
-    const localeTitle = CONFIG.i18n ? I18nService.getTranslationObject<string>(`${view.viewName}.title`) : null;
-    document.title = seoTitle || localeTitle || view.viewName;
+let announcer: HTMLElement | null = null;
+
+// A visually hidden polite live region, created on first use. Emptied first and filled
+// a moment later, so a title identical to the previous one is still announced (a timer,
+// not requestAnimationFrame: that one doesn't run in a background tab).
+function announce(message: string): void {
+  if (!announcer?.isConnected) {
+    const region = document.createElement('div');
+    region.setAttribute('role', 'status');
+    region.setAttribute('aria-live', 'polite');
+    region.setAttribute('data-nutin-announcer', '');
+    region.style.cssText =
+      'position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;' +
+      'overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;';
+    document.body.appendChild(region);
+    announcer = region;
   }
+  const region = announcer;
+  region.textContent = '';
+  setTimeout(() => { region.textContent = message; }, ANNOUNCE_DELAY);
+}
+
+export function getCurrentPath(): string {
+  return normalizePath(window.location.pathname);
+}
 
-  private static resolveSeoTitle(title: string | Record<string, string>): string | undefined {
-    if (typeof title !== 'object') return title;
+export function updateDocumentTitle(view: View, pattern: string): void {
+  const route = CONFIG.generateSEOFiles
+    ? CONFIG.seo?.routes?.find((r) => r.path === pattern)
+    : undefined;
+  const seoTitle = route?.title ? resolveSeoTitle(route.title) : undefined;
+  const localeTitle = (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) ? I18nService.getTranslationObject<string>(`${view.viewName}.title`) : null;
+  document.title = view.documentTitle?.() || seoTitle || localeTitle || view.viewName;
+}
+
+function resolveSeoTitle(title: string | Record<string, string>): string | undefined {
+  if (typeof title !== 'object') return title;
+  if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
     const lang = I18nService.currentLanguage;
     const defaultLang = I18nService.defaultLanguage;
     return title[lang] ?? title[defaultLang] ?? Object.values(title)[0];
   }
+  return Object.values(title)[0];
+}
 
-  public static matchPattern(pattern: string, path: string): Record<string, string> | null {
-    const paramNames: string[] = [];
+export function matchPattern(pattern: string, path: string): Record<string, string> | null {
+  const paramNames: string[] = [];
 
-    const regexPattern = pattern
-      .replace(/\/:([^/?]+)\?/g, (_, paramName) => {
-        paramNames.push(paramName);
+  // Splits on "/:param?" and ":param"; the static parts in between match literally.
+  const regexPattern = pattern
+    .split(/(\/:[^/?]+\?|:[^/]+)/)
+    .map((part) => {
+      const optional = part.match(/^\/:([^/?]+)\?$/);
+      if (optional) {
+        paramNames.push(optional[1]!);
         return `(?:/([^/]+))?`; // whole "/param" is optional
-      })
-      .replace(/:([^/]+)/g, (_, paramName) => {
-        paramNames.push(paramName);
+      }
+      const required = part.match(/^:([^/]+)$/);
+      if (required) {
+        paramNames.push(required[1]!);
         return `([^/]+)`;
-      });
+      }
+      return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('');
 
-    const regex = new RegExp(`^${regexPattern}$`);
-    const match = path.match(regex);
+  const regex = new RegExp(`^${regexPattern}$`);
+  const match = path.match(regex);
 
-    if (!match) return null;
+  if (!match) return null;
 
-    const params: Record<string, string> = {};
-    paramNames.forEach((name, i) => {
-      const value = match[i + 1];
-      if (value) {
-        params[name] = value;
-      }
-    });
-    return params;
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, i) => {
+    const value = match[i + 1];
+    if (value) {
+      params[name] = decodeParam(value);
+    }
+  });
+  return params;
+}
+
+// The path comes percent-encoded from the URL; a malformed escape is kept as-is.
+function decodeParam(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
   }
 }