@furystack/shades 13.2.2 → 15.0.0

package/src/services/location-service.tsx

@@ -1,174 +1,208 @@
-import { Injectable, type Injector } from '@furystack/inject'
+import type { Injector, Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
 import {
   deserializeQueryString as defaultDeserializeQueryString,
   serializeToQueryString as defaultSerializeToQueryString,
 } from '@furystack/rest'
 import { ObservableValue } from '@furystack/utils'
+
 /**
- * Singleton service that tracks browser location changes (pathname, search, hash)
- * and exposes them as observable values for reactive routing and URL-driven state.
+ * Overridable settings for {@link LocationService}. Bind a replacement factory
+ * via {@link useCustomSearchStateSerializer} to swap the URL query-string
+ * (de)serializers used by the service.
  */
-@Injectable({ lifetime: 'singleton' })
-export class LocationService implements Disposable {
-  constructor(
-    private readonly serializeToQueryString = defaultSerializeToQueryString,
-
-    public readonly deserializeQueryString = defaultDeserializeQueryString,
-  ) {
-    window.addEventListener('popstate', this.popStateListener)
-    window.addEventListener('hashchange', this.hashChangeListener)
-
-    this.onDeserializedLocationSearchChanged = new ObservableValue(this.deserializeQueryString(location.search))
-
-    this.originalPushState = window.history.pushState.bind(window.history)
-    window.history.pushState = ((...args: Parameters<typeof window.history.pushState>) => {
-      this.originalPushState(...args)
-      this.updateState()
-    }).bind(this)
-
-    this.originalReplaceState = window.history.replaceState.bind(window.history)
-    window.history.replaceState = ((...args: Parameters<typeof window.history.replaceState>) => {
-      this.originalReplaceState(...args)
-      this.updateState()
-    }).bind(this)
-  }
-
-  private originalPushState: typeof window.history.pushState
-  private originalReplaceState: typeof window.history.replaceState
+export interface LocationServiceSettings {
+  serialize: typeof defaultSerializeToQueryString
+  deserialize: typeof defaultDeserializeQueryString
+}
 
-  public [Symbol.dispose]() {
-    window.removeEventListener('popstate', this.popStateListener)
-    window.removeEventListener('hashchange', this.hashChangeListener)
-    this.onLocationSearchChanged[Symbol.dispose]()
-    this.onDeserializedLocationSearchChanged[Symbol.dispose]()
-    this.locationDeserializerObserver[Symbol.dispose]()
-    this.onLocationPathChanged[Symbol.dispose]()
-    this.onLocationHashChanged[Symbol.dispose]()
-
-    window.history.pushState = this.originalPushState
-    window.history.replaceState = this.originalReplaceState
-  }
+export const LocationServiceSettings: Token<LocationServiceSettings, 'singleton'> = defineService({
+  name: '@furystack/shades/LocationServiceSettings',
+  lifetime: 'singleton',
+  factory: () => ({
+    serialize: defaultSerializeToQueryString,
+    deserialize: defaultDeserializeQueryString,
+  }),
+})
 
+/**
+ * Singleton service that tracks browser location changes (pathname, search, hash)
+ * and exposes them as observable values for reactive routing and URL-driven state.
+ */
+export interface LocationService {
+  readonly deserializeQueryString: typeof defaultDeserializeQueryString
+  readonly onLocationPathChanged: ObservableValue<string>
+  readonly onLocationHashChanged: ObservableValue<string>
+  readonly onLocationSearchChanged: ObservableValue<string>
+  readonly onDeserializedLocationSearchChanged: ObservableValue<Record<string, unknown>>
+  readonly searchParamObservables: Map<string, ObservableValue<any>>
   /**
-   * Observable value that will be updated when the location pathname (e.g. /page/1) changes
+   * Synchronizes the observable state with the current browser location.
+   * Called internally after navigation events and history state changes.
    */
-  public onLocationPathChanged = new ObservableValue(new URL(location.href).pathname)
-
+  updateState(): void
+  /**
+   * Navigate to a path. Use this instead of raw history.pushState for SPA routing.
+   */
+  navigate(path: string): void
   /**
-   * Observable value that will be updated when the location hash (e.g. #hash) changes
+   * Replace the current history entry with a new path. Use this instead of raw
+   * history.replaceState for SPA redirects where the intermediate URL should
+   * not appear in the browser's back/forward stack.
    */
-  public onLocationHashChanged = new ObservableValue(location.hash.replace('#', ''))
-
+  replace(path: string): void
   /**
-   * Observable value that will be updated when the location search (e.g. ?search=1) changes
+   * Gets or creates an observable for a search parameter.
    */
-  public onLocationSearchChanged = new ObservableValue<string>(location.search)
+  useSearchParam<T>(key: string, defaultValue: T): ObservableValue<T>
+}
 
-  public onDeserializedLocationSearchChanged: ObservableValue<Record<string, unknown>>
+export const LocationService: Token<LocationService, 'singleton'> = defineService({
+  name: '@furystack/shades/LocationService',
+  lifetime: 'singleton',
+  factory: ({ inject, onDispose }) => {
+    const { serialize, deserialize } = inject(LocationServiceSettings)
+
+    const onLocationPathChanged = new ObservableValue(new URL(location.href).pathname)
+    const onLocationHashChanged = new ObservableValue(location.hash.replace('#', ''))
+    const onLocationSearchChanged = new ObservableValue<string>(location.search)
+    const onDeserializedLocationSearchChanged = new ObservableValue<Record<string, unknown>>(
+      deserialize(location.search),
+    )
+    const searchParamObservables = new Map<string, ObservableValue<any>>()
+
+    const updateState = (): void => {
+      onLocationPathChanged.setValue(location.pathname)
+      onLocationHashChanged.setValue(location.hash.replace('#', ''))
+      onLocationSearchChanged.setValue(location.search)
+    }
 
-  public locationDeserializerObserver = this.onLocationSearchChanged.subscribe((search) => {
-    this.onDeserializedLocationSearchChanged.setValue(this.deserializeQueryString(search))
-  })
+    const locationDeserializerObserver = onLocationSearchChanged.subscribe((search) => {
+      onDeserializedLocationSearchChanged.setValue(deserialize(search))
+    })
 
-  /**
-   * Synchronizes the observable state with the current browser location.
-   * Called internally after navigation events and history state changes.
-   */
-  public updateState = (() => {
-    this.onLocationPathChanged.setValue(location.pathname)
-    this.onLocationHashChanged.setValue(location.hash.replace('#', ''))
-    this.onLocationSearchChanged.setValue(location.search)
-  }).bind(this)
+    const popStateListener = (_ev: PopStateEvent): void => {
+      updateState()
+    }
+    const hashChangeListener = (_ev: HashChangeEvent): void => {
+      updateState()
+    }
+    window.addEventListener('popstate', popStateListener)
+    window.addEventListener('hashchange', hashChangeListener)
 
-  /**
-   * Navigate to a path. Use this instead of raw history.pushState for SPA routing.
-   * The LocationService interceptor ensures routing state is updated correctly.
-   */
-  public navigate(path: string): void {
-    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
-    history.pushState(null, '', path)
-    this.updateState()
-  }
+    const originalPushState = window.history.pushState.bind(window.history)
+    window.history.pushState = (...args: Parameters<typeof window.history.pushState>) => {
+      originalPushState(...args)
+      updateState()
+    }
 
-  /**
-   * Replace the current history entry with a new path. Use this instead of
-   * raw history.replaceState for SPA redirects (e.g. the intermediate URL
-   * should not appear in the browser's back/forward stack).
-   */
-  public replace(path: string): void {
-    // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
-    history.replaceState(null, '', path)
-    this.updateState()
-  }
+    const originalReplaceState = window.history.replaceState.bind(window.history)
+    window.history.replaceState = (...args: Parameters<typeof window.history.replaceState>) => {
+      originalReplaceState(...args)
+      updateState()
+    }
 
-  /**
-   * Internal cache of per-key search parameter observables created by {@link useSearchParam}.
-   */
-  public readonly searchParamObservables = new Map<string, ObservableValue<any>>()
+    const navigate = (path: string): void => {
+      // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.navigate() implementation.
+      history.pushState(null, '', path)
+      updateState()
+    }
 
-  /**
-   * Gets or creates an observable for a search parameter
-   * @param key The search param key (e.g. ?search=1 -> search)
-   * @param defaultValue The default value if not provided
-   * @returns An observable with the current value (or default value) of the search param
-   */
-  public useSearchParam<T>(key: string, defaultValue: T) {
-    const existing = this.searchParamObservables.get(key)
+    const replace = (path: string): void => {
+      // eslint-disable-next-line furystack/prefer-location-service -- This IS the LocationService.replace() implementation.
+      history.replaceState(null, '', path)
+      updateState()
+    }
 
-    if (!existing) {
-      const currentDeserialized = this.onDeserializedLocationSearchChanged.getValue()
+    const useSearchParam = <T,>(key: string, defaultValue: T): ObservableValue<T> => {
+      const existing = searchParamObservables.get(key)
+      if (existing) return existing as ObservableValue<T>
 
+      const currentDeserialized = onDeserializedLocationSearchChanged.getValue()
       const actualValue = Object.prototype.hasOwnProperty.call(currentDeserialized, key)
         ? (currentDeserialized[key] as T)
         : defaultValue
 
       const newObservable = new ObservableValue(actualValue)
-      this.searchParamObservables.set(key, newObservable)
+      searchParamObservables.set(key, newObservable)
 
       newObservable.subscribe((value) => {
-        const currentQueryStringObject = this.onDeserializedLocationSearchChanged.getValue()
+        const currentQueryStringObject = onDeserializedLocationSearchChanged.getValue()
         if (currentQueryStringObject[key] !== value) {
-          const params = this.serializeToQueryString({ ...currentQueryStringObject, [key]: value })
+          const params = serialize({ ...currentQueryStringObject, [key]: value })
           const newUrl = `${location.pathname}?${params}`
           // eslint-disable-next-line furystack/prefer-location-service -- Internal LocationService plumbing for search param sync.
           history.pushState({}, '', newUrl)
         }
       })
 
-      this.onDeserializedLocationSearchChanged.subscribe((search) => {
+      onDeserializedLocationSearchChanged.subscribe((search) => {
         const value = (search[key] as T) ?? defaultValue
-        this.searchParamObservables.get(key)?.setValue(value)
+        searchParamObservables.get(key)?.setValue(value)
       })
+
       return newObservable
     }
-    return existing as ObservableValue<T>
-  }
-
-  private popStateListener = (_ev: PopStateEvent) => {
-    this.updateState()
-  }
 
-  private hashChangeListener = ((_ev: HashChangeEvent) => {
-    this.updateState()
-  }).bind(this)
-}
+    onDispose(() => {
+      window.removeEventListener('popstate', popStateListener)
+      window.removeEventListener('hashchange', hashChangeListener)
+      window.history.pushState = originalPushState
+      window.history.replaceState = originalReplaceState
+      locationDeserializerObserver[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationSearchChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onDeserializedLocationSearchChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationPathChanged[Symbol.dispose]()
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      onLocationHashChanged[Symbol.dispose]()
+    })
+
+    return {
+      deserializeQueryString: deserialize,
+      onLocationPathChanged,
+      onLocationHashChanged,
+      onLocationSearchChanged,
+      onDeserializedLocationSearchChanged,
+      searchParamObservables,
+      updateState,
+      navigate,
+      replace,
+      useSearchParam,
+    }
+  },
+})
 
 /**
- * Configures custom serialization for URL search state.
- * Must be called **before** `LocationService` is first instantiated by the injector.
- * @param injector The root injector
- * @param serialize Function to serialize state to a query string
- * @param deserialize Function to deserialize a query string to state
+ * Configures custom (de)serialization for URL search state by binding
+ * {@link LocationServiceSettings} on the given injector.
+ *
+ * Must be called **before** any consumer resolves {@link LocationService}:
+ * the service patches `history.pushState` / `history.replaceState` and
+ * subscribes to `popstate` / `hashchange` on construction, and those
+ * listeners are only torn down when the owning injector is disposed.
+ * Rebinding after the first resolution would leak the previous instance,
+ * so this helper throws loudly if that happens.
+ *
+ * @param injector The root injector.
+ * @param serialize Function to serialize state to a query string.
+ * @param deserialize Function to deserialize a query string to state.
+ * @throws If {@link LocationService} has already been resolved on
+ *         `injector` (or any reachable ancestor).
  */
 export const useCustomSearchStateSerializer = (
   injector: Injector,
   serialize: typeof defaultSerializeToQueryString,
   deserialize: typeof defaultDeserializeQueryString,
-) => {
-  if (injector.cachedSingletons.has(LocationService)) {
-    throw new Error('useCustomSearchStateSerializer must be called before the LocationService is instantiated')
+): void => {
+  if (injector.isResolved(LocationService)) {
+    throw new Error(
+      'useCustomSearchStateSerializer must be called before LocationService is resolved for the first time. ' +
+        'Configure serializers during injector bootstrap (e.g. before the first render).',
+    )
   }
-
-  const locationService = new LocationService(serialize, deserialize)
-  injector.setExplicitInstance(locationService, LocationService)
+  injector.bind(LocationServiceSettings, () => ({ serialize, deserialize }))
+  injector.invalidate(LocationServiceSettings)
 }

package/src/services/route-match-service.spec.ts

@@ -1,44 +1,57 @@
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
 import { describe, expect, it, vi } from 'vitest'
 import type { MatchChainEntry } from '../components/nested-router.js'
 import { RouteMatchService } from './route-match-service.js'
 
 describe('RouteMatchService', () => {
-  it('should start with an empty match chain', () => {
-    using service = new RouteMatchService()
-    expect(service.currentMatchChain.getValue()).toEqual([])
+  it('should start with an empty match chain', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      expect(service.currentMatchChain.getValue()).toEqual([])
+    })
   })
 
-  it('should update the match chain', () => {
-    using service = new RouteMatchService()
-    const chain: MatchChainEntry[] = [
-      {
-        route: { component: () => ({}) as JSX.Element },
-        match: { path: '/about', params: {} },
-      },
-    ]
-    service.currentMatchChain.setValue(chain)
-    expect(service.currentMatchChain.getValue()).toBe(chain)
+  it('should update the match chain', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      const chain: MatchChainEntry[] = [
+        {
+          route: { component: () => ({}) as JSX.Element },
+          match: { path: '/about', params: {} },
+          query: null,
+          hash: undefined,
+        },
+      ]
+      service.currentMatchChain.setValue(chain)
+      expect(service.currentMatchChain.getValue()).toBe(chain)
+    })
   })
 
-  it('should notify subscribers on match chain change', () => {
-    using service = new RouteMatchService()
-    const listener = vi.fn()
-    using _subscription = service.currentMatchChain.subscribe(listener)
+  it('should notify subscribers on match chain change', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const service = i.get(RouteMatchService)
+      const listener = vi.fn()
+      using _subscription = service.currentMatchChain.subscribe(listener)
 
-    const chain: MatchChainEntry[] = [
-      {
-        route: { meta: { title: 'Home' }, component: () => ({}) as JSX.Element },
-        match: { path: '/', params: {} },
-      },
-    ]
-    service.currentMatchChain.setValue(chain)
+      const chain: MatchChainEntry[] = [
+        {
+          route: { meta: { title: 'Home' }, component: () => ({}) as JSX.Element },
+          match: { path: '/', params: {} },
+          query: null,
+          hash: undefined,
+        },
+      ]
+      service.currentMatchChain.setValue(chain)
 
-    expect(listener).toHaveBeenCalledWith(chain)
+      expect(listener).toHaveBeenCalledWith(chain)
+    })
   })
 
-  it('should dispose the observable on service disposal', () => {
-    const service = new RouteMatchService()
-    service[Symbol.dispose]()
+  it('should dispose the observable on injector disposal', async () => {
+    const injector = createInjector()
+    const service = injector.get(RouteMatchService)
+    await injector[Symbol.asyncDispose]()
 
     expect(() => service.currentMatchChain.setValue([])).toThrow()
   })

package/src/services/route-match-service.ts

@@ -1,4 +1,5 @@
-import { Injectable } from '@furystack/inject'
+import type { Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
 import { ObservableValue } from '@furystack/utils'
 import type { MatchChainEntry } from '../components/nested-router.js'
 
@@ -7,11 +8,19 @@ import type { MatchChainEntry } from '../components/nested-router.js'
  * NestedRouter as an observable. Consumers (breadcrumbs, document title,
  * navigation trees) subscribe to this instead of re-running route matching.
  */
-@Injectable({ lifetime: 'singleton' })
-export class RouteMatchService implements Disposable {
-  public readonly currentMatchChain = new ObservableValue<MatchChainEntry[]>([])
-
-  public [Symbol.dispose]() {
-    this.currentMatchChain[Symbol.dispose]()
-  }
+export interface RouteMatchService {
+  readonly currentMatchChain: ObservableValue<MatchChainEntry[]>
 }
+
+export const RouteMatchService: Token<RouteMatchService, 'singleton'> = defineService({
+  name: '@furystack/shades/RouteMatchService',
+  lifetime: 'singleton',
+  factory: ({ onDispose }) => {
+    const currentMatchChain = new ObservableValue<MatchChainEntry[]>([])
+    onDispose(() => {
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- Disposal is deferred to the injector's onDispose hook.
+      currentMatchChain[Symbol.dispose]()
+    })
+    return { currentMatchChain }
+  },
+})

package/src/services/route-meta-utils.spec.ts

@@ -1,15 +1,25 @@
-import { Injector } from '@furystack/inject'
-import { describe, expect, it } from 'vitest'
+import { createInjector, Injector } from '@furystack/inject'
+import { describe, expect, expectTypeOf, it } from 'vitest'
 import type { MatchChainEntry, NestedRoute } from '../components/nested-router.js'
-import { buildDocumentTitle, extractNavTree, resolveRouteTitle, resolveRouteTitles } from './route-meta-utils.js'
+import {
+  buildDocumentTitle,
+  extractNavTree,
+  type NavTreeNode,
+  resolveRouteTitle,
+  resolveRouteTitles,
+} from './route-meta-utils.js'
+
+type TestRoute = Pick<NestedRoute<unknown, any, any>, 'component'>
 
 describe('resolveRouteTitle', () => {
-  const injector = new Injector()
+  const injector = createInjector()
 
   it('should return undefined when no meta is configured', async () => {
     const entry: MatchChainEntry = {
       route: { component: () => ({}) as JSX.Element },
       match: { path: '/about', params: {} },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBeUndefined()
   })
@@ -18,6 +28,8 @@ describe('resolveRouteTitle', () => {
     const entry: MatchChainEntry = {
       route: { meta: {}, component: () => ({}) as JSX.Element },
       match: { path: '/about', params: {} },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBeUndefined()
   })
@@ -26,6 +38,8 @@ describe('resolveRouteTitle', () => {
     const entry: MatchChainEntry = {
       route: { meta: { title: 'About' }, component: () => ({}) as JSX.Element },
       match: { path: '/about', params: {} },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBe('About')
   })
@@ -37,6 +51,8 @@ describe('resolveRouteTitle', () => {
         component: () => ({}) as JSX.Element,
       },
       match: { path: '/users/42', params: { id: '42' } },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBe('User 42')
   })
@@ -53,6 +69,8 @@ describe('resolveRouteTitle', () => {
         component: () => ({}) as JSX.Element,
       },
       match: { path: '/movies/7', params: { id: '7' } },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBe('Movie 7')
   })
@@ -66,23 +84,29 @@ describe('resolveRouteTitle', () => {
         component: () => ({}) as JSX.Element,
       },
       match: { path: '/test', params: {} },
+      query: null,
+      hash: undefined,
     }
     expect(await resolveRouteTitle(entry, injector)).toBe('has-injector')
   })
 })
 
 describe('resolveRouteTitles', () => {
-  const injector = new Injector()
+  const injector = createInjector()
 
   it('should resolve all titles in a mixed chain', async () => {
     const chain: MatchChainEntry[] = [
       {
         route: { meta: { title: 'Media' }, component: () => ({}) as JSX.Element },
         match: { path: '/media', params: {} },
+        query: null,
+        hash: undefined,
       },
       {
         route: { meta: { title: 'Movies' }, component: () => ({}) as JSX.Element },
         match: { path: '/movies', params: {} },
+        query: null,
+        hash: undefined,
       },
       {
         route: {
@@ -90,6 +114,8 @@ describe('resolveRouteTitles', () => {
           component: () => ({}) as JSX.Element,
         },
         match: { path: '/7', params: { id: '7' } },
+        query: null,
+        hash: undefined,
       },
     ]
     const titles = await resolveRouteTitles(chain, injector)
@@ -106,10 +132,14 @@ describe('resolveRouteTitles', () => {
       {
         route: { meta: { title: 'Root' }, component: () => ({}) as JSX.Element },
         match: { path: '/', params: {} },
+        query: null,
+        hash: undefined,
       },
       {
         route: { component: () => ({}) as JSX.Element },
         match: { path: '/child', params: {} },
+        query: null,
+        hash: undefined,
       },
     ]
     const titles = await resolveRouteTitles(chain, injector)
@@ -155,7 +185,7 @@ describe('buildDocumentTitle', () => {
 
 describe('extractNavTree', () => {
   it('should extract a flat route tree', () => {
-    const routes: Record<string, NestedRoute<unknown>> = {
+    const routes: Record<string, NestedRoute<any, any, any>> = {
       '/about': { meta: { title: 'About' }, component: () => ({}) as JSX.Element },
       '/contact': { meta: { title: 'Contact' }, component: () => ({}) as JSX.Element },
     }
@@ -167,7 +197,7 @@ describe('extractNavTree', () => {
   })
 
   it('should extract nested routes recursively', () => {
-    const routes: Record<string, NestedRoute<unknown>> = {
+    const routes: Record<string, NestedRoute<any, any, any>> = {
       '/media': {
         meta: { title: 'Media' },
         component: () => ({}) as JSX.Element,
@@ -197,7 +227,7 @@ describe('extractNavTree', () => {
   })
 
   it('should handle root "/" parent path correctly', () => {
-    const routes: Record<string, NestedRoute<unknown>> = {
+    const routes: Record<string, NestedRoute<any, any, any>> = {
       '/': {
         meta: { title: 'Home' },
         component: () => ({}) as JSX.Element,
@@ -212,7 +242,7 @@ describe('extractNavTree', () => {
   })
 
   it('should compute correct fullPath for deeply nested routes (3+ levels)', () => {
-    const routes: Record<string, NestedRoute<unknown>> = {
+    const routes: Record<string, NestedRoute<any, any, any>> = {
       '/a': {
         meta: { title: 'A' },
         component: () => ({}) as JSX.Element,
@@ -234,10 +264,48 @@ describe('extractNavTree', () => {
   })
 
   it('should include routes without meta', () => {
-    const routes: Record<string, NestedRoute<unknown>> = {
+    const routes: Record<string, NestedRoute<any, any, any>> = {
       '/hidden': { component: () => ({}) as JSX.Element },
     }
     const tree = extractNavTree(routes)
     expect(tree[0].meta).toBeUndefined()
   })
+
+  describe('typed output', () => {
+    it('should narrow pattern and fullPath for a flat typed tree', () => {
+      const routes = {
+        '/about': { component: () => ({}) as JSX.Element } satisfies TestRoute,
+        '/contact': { component: () => ({}) as JSX.Element } satisfies TestRoute,
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const tree = extractNavTree(routes)
+      expectTypeOf(tree[0].pattern).toEqualTypeOf<'/about' | '/contact'>()
+      expectTypeOf(tree[0].fullPath).toEqualTypeOf<'/about' | '/contact'>()
+    })
+
+    it('should include nested composed paths in the fullPath union', () => {
+      const routes = {
+        '/media': {
+          component: () => ({}) as JSX.Element,
+          children: {
+            '/movies': { component: () => ({}) as JSX.Element } satisfies TestRoute,
+            '/music': { component: () => ({}) as JSX.Element } satisfies TestRoute,
+          },
+        },
+      } satisfies Record<string, NestedRoute<any, any, any>>
+
+      const tree = extractNavTree(routes)
+      expectTypeOf(tree[0].fullPath).toEqualTypeOf<'/media' | '/media/movies' | '/media/music'>()
+      expectTypeOf(tree[0].children).toEqualTypeOf<Array<NavTreeNode<typeof routes>> | undefined>()
+    })
+
+    it('should preserve backward compatibility with the widened default', () => {
+      const node: NavTreeNode = {
+        pattern: '/anything',
+        fullPath: '/anything',
+      }
+      expectTypeOf(node.pattern).toEqualTypeOf<string>()
+      expectTypeOf(node.fullPath).toEqualTypeOf<string>()
+    })
+  })
 })