@owlmeans/web-router 0.1.10 → 0.1.14

package/build/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAI7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,EAAE;IACvC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAA;IAEnC,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE;QACpB,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,OAAO,CAAC,QAAQ,GAAG,GAAG,EAAE;QACtB,OAAO,cAAc,CAAA;IACvB,CAAC,CAAA;IAED,OAAO,CAAC,SAAS,GAAG,GAAwC,EAAE;QAC5D,OAAO,SAAS,EAAO,CAAA;IACzB,CAAC,CAAA;IAED,OAAO,CAAC,WAAW,GAAG,GAAG,EAAE;QACzB,OAAO,WAAW,EAAE,CAAA;IACtB,CAAC,CAAA;IAED,OAAO,CAAC,WAAW,GAAG,GAAG,EAAE;QACzB,OAAO,WAAW,EAAE,CAAA;IACtB,CAAC,CAAA;IAED,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAwE,GAAM,EAAE,EAAE;IAC/G,GAAG,CAAC,eAAe,CAAC,oBAAoB,EAAE,CAAC,CAAA;AAC7C,CAAC,CAAA"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAkB,EAAE;IACtD,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAA;IACnC,OAAO,CAAC,cAAc,CAAC,uBAAuB,EAAE,CAAC,CAAA;IACjD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAmD,GAAM,EAAK,EAAE;IAC7F,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACxC,OAAO,CAAC,cAAc,CAAC,uBAAuB,EAAE,CAAC,CAAA;IACjD,OAAO,GAAG,CAAA;AACZ,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/web-router",
-  "version": "0.1.10",
+  "version": "0.1.14",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 63 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -21,18 +22,24 @@
     }
   },
   "peerDependencies": {
-    "react": "*",
-    "react-router": "^7.9.6"
+    "react": "*"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "nodemon": "^3.1.11",
-    "typescript": "^6.0.2"
+    "@owlmeans/test-ui": "^0.1.14",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^6.0.3",
+    "nodemon": "^3.1.14",
+    "playwright": "^1.61.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.2"
   },
   "dependencies": {
-    "@owlmeans/router": "^0.1.10"
+    "@owlmeans/context": "^0.1.14",
+    "@owlmeans/router": "^0.1.14"
   },
   "publishConfig": {
     "access": "public"

package/src/browser/chain.tsx

@@ -0,0 +1,35 @@
+import type { FC } from 'react'
+import { createElement, useContext } from 'react'
+import { RouterStateContext, OutletContext } from './context.js'
+
+/**
+ * Renders the matched route chain starting at `depth`.
+ *
+ * A matched route that carries no `Component` is a **pass-through**: it renders
+ * the next-deeper match, exactly like react-router's implicit `<Outlet/>` for
+ * element-less routes. OwlMeans module trees depend on this — grouping modules
+ * (e.g. `client-authentication` → `client-authentication:authentication`) have
+ * no handler, so `@owlmeans/client` emits `RouteObject`s without a `Component`
+ * for them. Rendering only the exact node at `depth` would leave the whole
+ * subtree blank whenever a group sits above the screen module.
+ */
+export const RouteChain: FC<{ depth: number }> = ({ depth }) => {
+  const state = useContext(RouterStateContext)
+  const matches = state?.matches ?? []
+
+  let current = depth
+  while (current < matches.length && matches[current].route.Component == null) {
+    current++
+  }
+
+  const Component = matches[current]?.route.Component
+  if (Component == null) {
+    return null
+  }
+
+  return createElement(
+    OutletContext.Provider,
+    { value: { depth: current } },
+    createElement(Component)
+  )
+}

package/src/browser/context.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react'
+import type { RouterState } from './types.js'
+
+export const RouterStateContext = createContext<RouterState | null>(null)
+
+export const OutletContext = createContext<{ depth: number }>({ depth: 0 })

package/src/browser/history.ts

@@ -0,0 +1,56 @@
+import type { Location } from '@owlmeans/router'
+import type { BrowserHistory } from './types.js'
+
+/**
+ * Minimal history wrapping the browser `window.history` + `popstate`. When no
+ * `window` is present (SSR) it returns an inert stub — the browser plugin is only
+ * *selected* in the browser, so this is purely defensive.
+ */
+export const createBrowserHistory = (): BrowserHistory => {
+  if (typeof window === 'undefined') {
+    const stub: Location = { pathname: '/', search: '', hash: '', state: null, key: '0' }
+    return {
+      get location() { return stub },
+      push: () => { }, replace: () => { }, go: () => { }, listen: () => () => { }
+    }
+  }
+
+  const listeners = new Set<(location: Location) => void>()
+  let counter = 0
+
+  const currentLocation = (): Location => ({
+    pathname: window.location.pathname,
+    search: window.location.search,
+    hash: window.location.hash,
+    state: window.history.state ?? null,
+    key: String(counter)
+  })
+
+  const notify = () => {
+    const location = currentLocation()
+    listeners.forEach(callback => callback(location))
+  }
+
+  window.addEventListener('popstate', () => {
+    counter++
+    notify()
+  })
+
+  return {
+    get location() { return currentLocation() },
+    push: (to, state) => {
+      counter++
+      window.history.pushState(state ?? null, '', to)
+      notify()
+    },
+    replace: (to, state) => {
+      window.history.replaceState(state ?? null, '', to)
+      notify()
+    },
+    go: delta => { window.history.go(delta) },
+    listen: callback => {
+      listeners.add(callback)
+      return () => { listeners.delete(callback) }
+    }
+  }
+}

package/src/browser/hooks.ts

@@ -0,0 +1,42 @@
+import { useContext, useMemo } from 'react'
+import type {
+  Location, NavigateFunction, RouteParams, SetSearchParams, UseSearchParamsHook
+} from '@owlmeans/router'
+import { RouterStateContext } from './context.js'
+
+const useRouterState = () => {
+  const state = useContext(RouterStateContext)
+  if (state == null) {
+    throw new Error('owlmeans-browser-router: router hook used outside of the router provider')
+  }
+  return state
+}
+
+export const useParams = <T extends RouteParams = RouteParams>(): T => {
+  const { matches } = useRouterState()
+  return (matches[matches.length - 1]?.params ?? {}) as T
+}
+
+export const useLocation = (): Location => useRouterState().location
+
+export const useNavigate = (): NavigateFunction => useRouterState().navigate
+
+export const useSearchParams: UseSearchParamsHook = init => {
+  const { location, navigate } = useRouterState()
+
+  const search = useMemo(
+    () => new URLSearchParams(location.search !== '' ? location.search : (init ?? '')),
+    [location.search]
+  )
+
+  const setSearch: SetSearchParams = (next, options) => {
+    const resolved = typeof next === 'function'
+      ? next(new URLSearchParams(location.search))
+      : next instanceof URLSearchParams ? next : new URLSearchParams(next)
+    const query = resolved.toString()
+    const path = `${location.pathname}${query !== '' ? `?${query}` : ''}${location.hash ?? ''}`
+    navigate(path, { replace: options?.replace, state: options?.state })
+  }
+
+  return [search, setSearch]
+}

package/src/browser/outlet.tsx

@@ -0,0 +1,16 @@
+import type { FC } from 'react'
+import { createElement, useContext } from 'react'
+import { OutletContext } from './context.js'
+import { RouteChain } from './chain.js'
+
+/**
+ * Renders the next-deeper matched route. Depth is tracked via `OutletContext`, so
+ * nested `<Outlet/>`s walk down the match chain — composing with the renderer in
+ * `@owlmeans/client` (parent components emit `<Outlet/>`). Component-less matches
+ * in between are skipped by `RouteChain` (implicit pass-through).
+ */
+export const Outlet: FC = () => {
+  const { depth } = useContext(OutletContext)
+
+  return createElement(RouteChain, { depth: depth + 1 })
+}

package/src/browser/plugin.ts

@@ -0,0 +1,29 @@
+import type { LibraryRouter, RouterPlugin } from '@owlmeans/router'
+import { flattenRoutes, rankRouteBranches } from '@owlmeans/router'
+import { BROWSER_ROUTER } from '../consts.js'
+import { BrowserRouterProvider } from './provider.js'
+import { Outlet } from './outlet.js'
+import { useLocation, useNavigate, useParams, useSearchParams } from './hooks.js'
+import type { OwlLibraryRouter } from './types.js'
+
+/**
+ * The default OwlMeans in-browser routing plugin. Standard URL routing over the
+ * browser History API. Matches always (priority 0), so it is the universal
+ * fallback in the browser; a higher-priority SSR plugin can outrank it later.
+ */
+export const makeBrowserRouterPlugin = (): RouterPlugin => ({
+  alias: BROWSER_ROUTER,
+  priority: 0,
+  mode: 'browser',
+  match: () => true,
+  compile: routes => ({
+    routes,
+    branches: rankRouteBranches(flattenRoutes(routes))
+  } satisfies OwlLibraryRouter as LibraryRouter),
+  provider: () => BrowserRouterProvider,
+  outlet: () => Outlet,
+  useParams,
+  useLocation,
+  useNavigate,
+  useSearchParams
+})

package/src/browser/provider.tsx

@@ -0,0 +1,53 @@
+import type { FC } from 'react'
+import { createElement, useEffect, useMemo, useRef, useState } from 'react'
+import type { LibraryRouter, Location, NavigateFunction } from '@owlmeans/router'
+import { matchRoutes } from '@owlmeans/router'
+import { createBrowserHistory } from './history.js'
+import { RouterStateContext } from './context.js'
+import { RouteChain } from './chain.js'
+import type { OwlLibraryRouter } from './types.js'
+
+/**
+ * Renders the OwlMeans library router. Subscribes to history, recomputes the
+ * matched route chain on navigation, and renders the top match. Initial render
+ * matches synchronously from `window.location` to avoid a first-paint flash.
+ */
+export const BrowserRouterProvider: FC<{ router: LibraryRouter }> = ({ router }) => {
+  const lib = router as OwlLibraryRouter
+  const historyRef = useRef(createBrowserHistory())
+  const history = historyRef.current
+
+  const [location, setLocation] = useState<Location>(() => history.location)
+
+  useEffect(() => history.listen(setLocation), [])
+
+  const matches = useMemo(
+    () => matchRoutes(lib.branches, location.pathname) ?? [],
+    [lib, location.pathname]
+  )
+
+  const navigate = useMemo<NavigateFunction>(() => ((to: string | number | { pathname?: string, search?: string, hash?: string }, options?: { replace?: boolean, state?: any }) => {
+    if (typeof to === 'number') {
+      history.go(to)
+      return
+    }
+    if (typeof to === 'string' && to.startsWith('http')) {
+      window.location.href = to
+      return
+    }
+    const path = typeof to === 'string'
+      ? to
+      : `${to.pathname ?? ''}${to.search ?? ''}${to.hash ?? ''}`
+    if (options?.replace) {
+      history.replace(path, options.state)
+    } else {
+      history.push(path, options?.state)
+    }
+  }) as NavigateFunction, [history])
+
+  return createElement(
+    RouterStateContext.Provider,
+    { value: { location, matches, navigate } },
+    createElement(RouteChain, { depth: 0 })
+  )
+}

package/src/browser/types.ts

@@ -0,0 +1,22 @@
+import type { Location, NavigateFunction, RouteMatch, RouteObject, RouteBranch } from '@owlmeans/router'
+
+/** The compiled library router produced by the browser plugin's `compile`. */
+export interface OwlLibraryRouter {
+  routes: RouteObject[]
+  branches: RouteBranch[]
+}
+
+/** Value carried by the router state React context. */
+export interface RouterState {
+  location: Location
+  matches: RouteMatch[]
+  navigate: NavigateFunction
+}
+
+export interface BrowserHistory {
+  readonly location: Location
+  push: (to: string, state?: any) => void
+  replace: (to: string, state?: any) => void
+  go: (delta: number) => void
+  listen: (callback: (location: Location) => void) => () => void
+}

package/src/consts.ts

@@ -0,0 +1,2 @@
+
+export const BROWSER_ROUTER = 'owlmeans-browser-router'

package/src/index.ts

@@ -1,2 +1,10 @@
 
+export * from './consts.js'
 export * from './service.js'
+export * from './browser/plugin.js'
+export type * from './browser/types.js'
+export { BrowserRouterProvider } from './browser/provider.js'
+export { Outlet } from './browser/outlet.js'
+export { RouteChain } from './browser/chain.js'
+export { createBrowserHistory } from './browser/history.js'
+export { useParams, useLocation, useNavigate, useSearchParams } from './browser/hooks.js'

package/src/service.ts

@@ -1,36 +1,25 @@
-import type { RouteParams } from "@owlmeans/router"
-import { makeRouterService } from "@owlmeans/router"
-import { RouterProvider, useNavigate } from "react-router"
-import { Outlet, useLocation, useParams } from "react-router"
-import type { ClientConfig } from "@owlmeans/client-context"
-import type { ClientContext } from "@owlmeans/client"
-
-export const makeWebRouterService = () => {
+import type { BasicConfig, BasicContext } from "@owlmeans/context"
+import type { RouterService } from "@owlmeans/router"
+import { ensureRouterService, makeRouterService } from "@owlmeans/router"
+import { makeBrowserRouterPlugin } from "./browser/plugin.js"
+
+/**
+ * Build a router service pre-loaded with the OwlMeans browser plugin. Kept for
+ * back-compat; prefer `appendWebRouter` which reuses an existing host.
+ */
+export const makeWebRouterService = (): RouterService => {
   const service = makeRouterService()
-
-  service.outlet = () => {
-    return Outlet
-  }
-
-  service.provider = () => {
-    return RouterProvider
-  }
-
-  service.useParams = <T extends RouteParams = RouteParams>() => {
-    return useParams() as T
-  }
-
-  service.useLocation = () => {
-    return useLocation()
-  }
-
-  service.useNavigate = () => {
-    return useNavigate()
-  }
-
+  service.registerPlugin(makeBrowserRouterPlugin())
   return service
 }
 
-export const appendWebRouter = <C extends ClientConfig, T extends ClientContext<C> = ClientContext<C>>(ctx: T) => {
-  ctx.registerService(makeWebRouterService())
+/**
+ * Register the OwlMeans in-browser routing plugin as the default on a context.
+ * Idempotent w.r.t. the router host — if another plugin (e.g. react-router) is
+ * already registered, this one is added alongside and selected by the cascade.
+ */
+export const appendWebRouter = <C extends BasicConfig, T extends BasicContext<C>>(ctx: T): T => {
+  const service = ensureRouterService(ctx)
+  service.registerPlugin(makeBrowserRouterPlugin())
+  return ctx
 }

package/tests/context.ts

@@ -0,0 +1,33 @@
+import { createServer } from 'vite'
+import react from '@vitejs/plugin-react'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+let url: string | null = null
+
+/**
+ * Boot a Vite dev server serving `tests/harness/` (a real HTTP origin — the
+ * OwlMeans router needs the History API, which a `data:` URL cannot provide).
+ * One server per `bun test` process; the harness renders the routing app.
+ */
+export const getHarnessUrl = async (): Promise<string> => {
+  if (url != null) return url
+  const server = await createServer({
+    configFile: false,
+    root: resolve(here, './harness'),
+    plugins: [react()],
+    // Single React instance so hooks work across the workspace-linked plugin.
+    resolve: { dedupe: ['react', 'react-dom'] },
+    server: { port: 0 },
+    logLevel: 'warn'
+  })
+  await server.listen()
+  const local = server.resolvedUrls?.local?.[0]
+  if (local == null) throw new Error('vite did not expose a local URL')
+  url = local
+  return url
+}
+
+export const HARNESS_URL = await getHarnessUrl()

package/tests/harness/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>@owlmeans/web-router routing e2e</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/mount.tsx"></script>
+  </body>
+</html>

package/tests/harness/mount.tsx

@@ -0,0 +1,60 @@
+import { createElement as h } from 'react'
+import { createRoot } from 'react-dom/client'
+import type { RouteObject } from '@owlmeans/router'
+import {
+  makeBrowserRouterPlugin, Outlet, useNavigate, useParams, useSearchParams
+} from '@owlmeans/web-router'
+
+// A small but real app driven by the OwlMeans in-browser routing plugin. The
+// e2e spec navigates this in a real chromium and asserts against the rendered
+// DOM + the browser URL/history.
+
+const Nav = () => {
+  const navigate = useNavigate()
+  return h('nav', null,
+    h('button', { id: 'nav-home', onClick: () => navigate('/') }, 'home'),
+    h('button', { id: 'nav-users', onClick: () => navigate('/users') }, 'users'),
+    h('button', { id: 'nav-user', onClick: () => navigate('/users/42?token=abc') }, 'user-42'),
+    h('button', { id: 'nav-settings', onClick: () => navigate('/users/settings') }, 'settings')
+  )
+}
+
+const Layout = () => h('div', { id: 'layout' }, h('h1', null, 'app'), h(Nav), h(Outlet))
+const Home = () => h('div', { id: 'home' }, 'home-screen')
+const Users = () => h('div', { id: 'users' }, 'users-screen', h(Outlet))
+const UsersIndex = () => h('div', { id: 'users-index' }, 'users-index-screen')
+const Settings = () => h('div', { id: 'settings' }, 'settings-screen')
+const Leaf = () => h('div', { id: 'leaf' }, 'leaf-screen')
+const Deep = () => h('div', { id: 'deep' }, 'deep-screen')
+const User = () => {
+  const { id } = useParams()
+  const [query] = useSearchParams()
+  return h('div', { id: 'user' }, `user:${id}:token:${query.get('token') ?? 'none'}`)
+}
+
+const routes: RouteObject[] = [
+  {
+    path: '', Component: Layout, children: [
+      { index: true, Component: Home },
+      {
+        path: 'users', Component: Users, children: [
+          { index: true, Component: UsersIndex },
+          { path: 'settings', Component: Settings }, // static must outrank :id
+          // component-less grouping node between two rendered routes: <Outlet/> must
+          // fall through it instead of stopping (react-router's implicit outlet)
+          { path: 'nested', children: [{ path: 'deep', Component: Deep }] },
+          { path: ':id', Component: User }
+        ]
+      }
+    ]
+  },
+  // component-less grouping node at the very top of the chain — this is the shape
+  // `@owlmeans/client` emits for modules without a handler (e.g. `client-authentication`)
+  { path: 'group', children: [{ path: 'leaf', Component: Leaf }] }
+]
+
+const plugin = makeBrowserRouterPlugin()
+const Provider = plugin.provider()
+const router = plugin.compile(routes)
+
+createRoot(document.getElementById('root')!).render(h(Provider, { router }))

package/tests/routing.spec.ts

@@ -0,0 +1,100 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { closeBrowser, withPage } from '@owlmeans/test-ui'
+import { HARNESS_URL } from './context.js'
+
+const at = (path: string) => new URL(path, HARNESS_URL).toString()
+
+afterAll(async () => { await closeBrowser() })
+
+describe('@owlmeans/web-router — OwlMeans browser routing (chromium e2e)', () => {
+  test('renders the index route inside the layout at /', async () => {
+    await withPage(async page => {
+      await page.goto(HARNESS_URL)
+      await page.waitForSelector('#home')
+      expect(await page.locator('#layout').isVisible()).toBe(true)
+      expect(await page.locator('#home').textContent()).toContain('home-screen')
+    })
+  })
+
+  test('programmatic navigate resolves nested route, params and search', async () => {
+    await withPage(async page => {
+      await page.goto(HARNESS_URL)
+      await page.waitForSelector('#nav-user')
+      await page.click('#nav-user')
+      await page.waitForSelector('#user')
+      // real browser URL updated via the History API
+      expect(new URL(page.url()).pathname).toBe('/users/42')
+      expect(new URL(page.url()).search).toBe('?token=abc')
+      // nested outlet renders parent + child
+      expect(await page.locator('#users').textContent()).toContain('users-screen')
+      // useParams + useSearchParams resolve
+      expect(await page.locator('#user').textContent()).toBe('user:42:token:abc')
+    })
+  })
+
+  test('nested index route renders at /users', async () => {
+    await withPage(async page => {
+      await page.goto(HARNESS_URL)
+      await page.waitForSelector('#nav-users')
+      await page.click('#nav-users')
+      await page.waitForSelector('#users-index')
+      expect(new URL(page.url()).pathname).toBe('/users')
+      expect(await page.locator('#users-index').textContent()).toContain('users-index-screen')
+    })
+  })
+
+  test('static segment outranks the :id dynamic sibling', async () => {
+    await withPage(async page => {
+      await page.goto(at('users/settings'))
+      await page.waitForSelector('#settings')
+      expect(await page.locator('#settings').textContent()).toContain('settings-screen')
+      expect(await page.locator('#user').count()).toBe(0)
+    })
+  })
+
+  test('deep-links directly to a :param URL (synchronous initial match)', async () => {
+    await withPage(async page => {
+      await page.goto(at('users/7?token=xyz'))
+      await page.waitForSelector('#user')
+      expect(await page.locator('#user').textContent()).toBe('user:7:token:xyz')
+    })
+  })
+
+  test('renders through a component-less group at the top of the chain', async () => {
+    await withPage(async page => {
+      await page.goto(at('group/leaf'))
+      await page.waitForSelector('#leaf')
+      expect(await page.locator('#leaf').textContent()).toContain('leaf-screen')
+      // the group carries no Component — it must not swallow the whole subtree
+      expect(await page.locator('#layout').count()).toBe(0)
+    })
+  })
+
+  test('outlet falls through a component-less group in the middle of the chain', async () => {
+    await withPage(async page => {
+      await page.goto(at('users/nested/deep'))
+      await page.waitForSelector('#deep')
+      expect(await page.locator('#layout').isVisible()).toBe(true)
+      expect(await page.locator('#users').textContent()).toContain('users-screen')
+      expect(await page.locator('#deep').textContent()).toContain('deep-screen')
+    })
+  })
+
+  test('browser back/forward restores the matched route', async () => {
+    await withPage(async page => {
+      await page.goto(HARNESS_URL)
+      await page.waitForSelector('#home')
+      await page.click('#nav-user')
+      await page.waitForSelector('#user')
+
+      await page.goBack()
+      await page.waitForSelector('#home')
+      expect(new URL(page.url()).pathname).toBe('/')
+
+      await page.goForward()
+      await page.waitForSelector('#user')
+      expect(new URL(page.url()).pathname).toBe('/users/42')
+      expect(await page.locator('#user').textContent()).toBe('user:42:token:abc')
+    })
+  })
+})

package/tsconfig.json

@@ -7,5 +7,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }