@tooee/router 0.1.8

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+import type React from "react";
+import type { StateCache } from "./state-cache.js";
+export interface RouteDefinition<TParams = Record<string, unknown>> {
+    id: string;
+    parent?: RouteDefinition;
+    component: React.ComponentType;
+    title?: string | ((opts: {
+        params: TParams;
+    }) => string);
+    loader?: (opts: {
+        params: TParams;
+    }) => Promise<unknown>;
+    pendingComponent?: React.ComponentType;
+    errorComponent?: React.ComponentType<{
+        error: Error;
+    }>;
+}
+export interface StackEntry {
+    routeId: string;
+    params: Record<string, unknown>;
+}
+export interface RouterState {
+    stack: StackEntry[];
+}
+export type RouterAction = {
+    type: "push";
+    routeId: string;
+    params?: Record<string, unknown>;
+} | {
+    type: "pop";
+} | {
+    type: "replace";
+    routeId: string;
+    params?: Record<string, unknown>;
+} | {
+    type: "reset";
+    routeId: string;
+    params?: Record<string, unknown>;
+};
+export interface RouterOptions {
+    routes: RouteDefinition[];
+    defaultRoute: string;
+    initialParams?: Record<string, unknown>;
+}
+export interface RouterInstance {
+    push(routeId: string, params?: Record<string, unknown>): void;
+    pop(): void;
+    replace(routeId: string, params?: Record<string, unknown>): void;
+    reset(routeId: string, params?: Record<string, unknown>): void;
+    canGoBack(): boolean;
+    readonly currentRoute: StackEntry;
+    readonly stack: readonly StackEntry[];
+    readonly stateCache: StateCache;
+    subscribe(listener: () => void): () => void;
+    getRouteDefinition(routeId: string): RouteDefinition | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,eAAe,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,SAAS,EAAE,KAAK,CAAC,aAAa,CAAA;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACxD,gBAAgB,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IACtC,cAAc,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;CACvD;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAExE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC7D,GAAG,IAAI,IAAI,CAAA;IACX,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC9D,SAAS,IAAI,OAAO,CAAA;IACpB,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAA;CACjE"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tooee/router",
+  "version": "0.1.8",
+  "description": "Stack-based router for Tooee terminal apps",
+  "license": "MIT",
+  "author": "Gareth Andrew",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gingerhendrix/tooee.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://github.com/gingerhendrix/tooee",
+  "bugs": "https://github.com/gingerhendrix/tooee/issues",
+  "keywords": [
+    "tui",
+    "terminal",
+    "cli",
+    "opentui",
+    "router",
+    "navigation"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "@tooee/source": "./src/index.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.1.67",
+    "@opentui/react": "^0.1.67",
+    "@tooee/commands": "0.1.8",
+    "@types/bun": "^1.3.5",
+    "@types/react": "^19.1.10",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@opentui/core": "^0.1.67",
+    "@opentui/react": "^0.1.67",
+    "@tooee/commands": "0.1.8",
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}

package/src/action-types.ts

@@ -0,0 +1,12 @@
+export interface NavigateResult {
+  type: "navigate"
+  route: string
+  params?: Record<string, unknown>
+  mode?: "push" | "replace"
+}
+
+export interface BackResult {
+  type: "back"
+}
+
+export type ActionNavigationResult = NavigateResult | BackResult

package/src/command-scope.tsx

@@ -0,0 +1,15 @@
+import { useCommand } from "@tooee/commands"
+import { useRouter } from "./hooks.js"
+
+export function useRouterCommands() {
+  const router = useRouter()
+
+  useCommand({
+    id: "router.back",
+    title: "Go back",
+    hotkey: "backspace",
+    modes: ["cursor"],
+    when: () => router.canGoBack(),
+    handler: () => router.pop(),
+  })
+}

package/src/context.tsx

@@ -0,0 +1,60 @@
+import { createContext, useContext, useEffect, useSyncExternalStore } from "react"
+import type { ReactNode } from "react"
+import type { RouterInstance, StackEntry } from "./types.js"
+
+// Contexts
+
+const RouterInstanceContext = createContext<RouterInstance | null>(null)
+const RouterStackContext = createContext<readonly StackEntry[]>([])
+export const StackEntryIndexContext = createContext<number>(0)
+
+// Provider
+
+export interface RouterProviderProps {
+  router: RouterInstance
+  initialRoute?: string
+  initialParams?: Record<string, unknown>
+  children: ReactNode
+}
+
+export function RouterProvider({
+  router,
+  initialRoute,
+  initialParams,
+  children,
+}: RouterProviderProps) {
+  useEffect(() => {
+    if (initialRoute && router.currentRoute.routeId !== initialRoute) {
+      router.reset(initialRoute, initialParams)
+    }
+  }, []) // only on mount
+
+  const stack = useSyncExternalStore(
+    router.subscribe,
+    () => router.stack,
+  )
+
+  return (
+    <RouterInstanceContext value={router}>
+      <RouterStackContext value={stack}>
+        {children}
+      </RouterStackContext>
+    </RouterInstanceContext>
+  )
+}
+
+// Internal hooks
+
+export function useRouterInstance(): RouterInstance {
+  const ctx = useContext(RouterInstanceContext)
+  if (!ctx) throw new Error("useRouterInstance must be used within RouterProvider")
+  return ctx
+}
+
+export function useRouterStack(): readonly StackEntry[] {
+  return useContext(RouterStackContext)
+}
+
+export function useStackEntryIndex(): number {
+  return useContext(StackEntryIndexContext)
+}

package/src/create-route.ts

@@ -0,0 +1,7 @@
+import type { RouteDefinition } from "./types.js"
+
+export function createRoute<TParams = Record<string, unknown>>(
+  options: RouteDefinition<TParams>,
+): RouteDefinition<TParams> {
+  return options
+}

package/src/create-router.ts

@@ -0,0 +1,91 @@
+import type {
+  RouterOptions,
+  RouterInstance,
+  RouterState,
+  RouteDefinition,
+  StackEntry,
+} from "./types.js"
+import { stackReducer } from "./stack.js"
+import { StateCache } from "./state-cache.js"
+
+export function createRouter(options: RouterOptions): RouterInstance {
+  const routeMap = new Map<string, RouteDefinition>()
+  for (const route of options.routes) {
+    routeMap.set(route.id, route)
+  }
+
+  if (!routeMap.has(options.defaultRoute)) {
+    throw new Error(`Default route "${options.defaultRoute}" not found in routes`)
+  }
+
+  let state: RouterState = {
+    stack: [
+      {
+        routeId: options.defaultRoute,
+        params: options.initialParams ?? {},
+      },
+    ],
+  }
+
+  const listeners = new Set<() => void>()
+  const stateCache = new StateCache()
+
+  function dispatch(action: Parameters<typeof stackReducer>[1]) {
+    if (action.type !== "pop" && !routeMap.has(action.routeId)) {
+      throw new Error(`Route "${action.routeId}" not found`)
+    }
+    const prev = state
+    const next = stackReducer(state, action)
+    if (next !== state) {
+      if (action.type === "pop" && prev.stack.length > 1) {
+        const poppedIndex = prev.stack.length - 1
+        const poppedEntry = prev.stack[poppedIndex]
+        stateCache.clear(`${poppedIndex}:${poppedEntry.routeId}`)
+      } else if (action.type === "reset") {
+        stateCache.clearAll()
+      }
+      state = next
+      for (const listener of listeners) {
+        listener()
+      }
+    }
+  }
+
+  const instance: RouterInstance = {
+    push(routeId, params) {
+      dispatch({ type: "push", routeId, params })
+    },
+    pop() {
+      dispatch({ type: "pop" })
+    },
+    replace(routeId, params) {
+      dispatch({ type: "replace", routeId, params })
+    },
+    reset(routeId, params) {
+      dispatch({ type: "reset", routeId, params })
+    },
+    canGoBack() {
+      return state.stack.length > 1
+    },
+    get currentRoute(): StackEntry {
+      return state.stack[state.stack.length - 1]
+    },
+    get stack(): readonly StackEntry[] {
+      return state.stack
+    },
+    get stateCache() {
+      return stateCache
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    getRouteDefinition(routeId) {
+      return routeMap.get(routeId)
+    },
+  }
+
+  return instance
+}

package/src/focus.tsx

@@ -0,0 +1,23 @@
+import { createContext, useContext, useEffect, useMemo, useRef } from "react"
+import type { ReactNode } from "react"
+
+const ScreenFocusContext = createContext({ isFocused: false })
+
+export function ScreenFocusProvider({ active, children }: { active: boolean; children: ReactNode }) {
+  const value = useMemo(() => ({ isFocused: active }), [active])
+  return <ScreenFocusContext value={value}>{children}</ScreenFocusContext>
+}
+
+export function useScreenFocus() {
+  return useContext(ScreenFocusContext)
+}
+
+export function useScreenEffect(effect: () => void | (() => void)) {
+  const { isFocused } = useScreenFocus()
+  const effectRef = useRef(effect)
+  effectRef.current = effect
+  useEffect(() => {
+    if (!isFocused) return
+    return effectRef.current()
+  }, [isFocused])
+}

package/src/hooks.ts

@@ -0,0 +1,85 @@
+import { useCallback } from "react"
+import type { RouterInstance, StackEntry } from "./types.js"
+import type { ActionNavigationResult } from "./action-types.js"
+import { useRouterInstance, useRouterStack, useStackEntryIndex } from "./context.js"
+import { useRouteDataContext } from "./loader.js"
+
+export function useNavigate() {
+  const router = useRouterInstance()
+  return {
+    push: useCallback(
+      (routeId: string, params?: Record<string, unknown>) => router.push(routeId, params),
+      [router],
+    ),
+    pop: useCallback(() => router.pop(), [router]),
+    replace: useCallback(
+      (routeId: string, params?: Record<string, unknown>) => router.replace(routeId, params),
+      [router],
+    ),
+    reset: useCallback(
+      (routeId: string, params?: Record<string, unknown>) => router.reset(routeId, params),
+      [router],
+    ),
+  }
+}
+
+export function useParams<T = Record<string, unknown>>(): T {
+  const stack = useRouterStack()
+  const entry = stack[stack.length - 1]
+  return (entry?.params ?? {}) as T
+}
+
+export function useRouteData<T = unknown>(): T | undefined {
+  return useRouteDataContext<T>()
+}
+
+export function useCurrentRoute(): StackEntry {
+  const stack = useRouterStack()
+  return stack[stack.length - 1]
+}
+
+export function useCanGoBack(): boolean {
+  const stack = useRouterStack()
+  return stack.length > 1
+}
+
+export function useRouter(): RouterInstance {
+  return useRouterInstance()
+}
+
+export function useActionResultHandler() {
+  const router = useRouterInstance()
+  return useCallback(
+    (result: ActionNavigationResult) => {
+      if (result.type === "navigate") {
+        if (result.mode === "replace") {
+          router.replace(result.route, result.params)
+        } else {
+          router.push(result.route, result.params)
+        }
+      } else if (result.type === "back") {
+        router.pop()
+      }
+    },
+    [router],
+  )
+}
+
+export function useScreenState<T>(): {
+  savedState: T | undefined
+  saveState: (state: T) => void
+} {
+  const router = useRouterInstance()
+  const stackIndex = useStackEntryIndex()
+  const stack = useRouterStack()
+  const entry = stack[stackIndex]
+  const key = `${stackIndex}:${entry.routeId}`
+
+  return {
+    savedState: router.stateCache.restore<T>(key),
+    saveState: useCallback(
+      (state: T) => router.stateCache.save(key, state),
+      [router.stateCache, key],
+    ),
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export type {
+  RouteDefinition,
+  StackEntry,
+  RouterState,
+  RouterAction,
+  RouterOptions,
+  RouterInstance,
+} from "./types.js"
+
+export { createRoute } from "./create-route.js"
+export { createRouter } from "./create-router.js"
+export { stackReducer } from "./stack.js"
+export { RouterProvider } from "./context.js"
+export type { RouterProviderProps } from "./context.js"
+export { Outlet, getRouteChain } from "./outlet.js"
+export {
+  useNavigate,
+  useParams,
+  useRouteData,
+  useCurrentRoute,
+  useCanGoBack,
+  useRouter,
+  useScreenState,
+  useActionResultHandler,
+} from "./hooks.js"
+export type {
+  NavigateResult,
+  BackResult,
+  ActionNavigationResult,
+} from "./action-types.js"
+export { ScreenFocusProvider, useScreenFocus, useScreenEffect } from "./focus.js"
+export { StateCache } from "./state-cache.js"
+export { useRouterCommands } from "./command-scope.js"

package/src/loader.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext } from "react"
+import type { ReactNode } from "react"
+
+// Context for route loader data
+
+const RouteDataContext = createContext<unknown>(undefined)
+
+export function RouteDataProvider({
+  data,
+  children,
+}: {
+  data: unknown
+  children: ReactNode
+}) {
+  return <RouteDataContext value={data}>{children}</RouteDataContext>
+}
+
+export function useRouteDataContext<T = unknown>(): T | undefined {
+  return useContext(RouteDataContext) as T | undefined
+}

package/src/outlet.tsx

@@ -0,0 +1,118 @@
+import { createContext, createElement, useContext, useEffect, useState } from "react"
+import type { ReactNode } from "react"
+import type { RouteDefinition, StackEntry } from "./types.js"
+import { useRouterInstance, useRouterStack, StackEntryIndexContext } from "./context.js"
+import { ScreenFocusProvider } from "./focus.js"
+import { RouteDataProvider } from "./loader.js"
+
+// Depth tracking context
+
+const OutletDepthContext = createContext<number>(0)
+
+// Helper: walk parent chain and return [root, ..., leaf]
+
+export function getRouteChain(
+  routeMap: { get(id: string): RouteDefinition | undefined },
+  routeId: string,
+): RouteDefinition[] {
+  const chain: RouteDefinition[] = []
+  let current = routeMap.get(routeId)
+  while (current) {
+    chain.unshift(current)
+    current = current.parent
+  }
+  return chain
+}
+
+// RouteRenderer: handles loader lifecycle for a route
+
+function RouteRenderer({
+  entry,
+  routeDef,
+  children,
+}: {
+  entry: StackEntry
+  routeDef: RouteDefinition
+  children: ReactNode
+}) {
+  const [data, setData] = useState<unknown>(undefined)
+  const [loading, setLoading] = useState(!!routeDef.loader)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    if (!routeDef.loader) return
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    routeDef
+      .loader({ params: entry.params })
+      .then((result) => {
+        if (!cancelled) { setData(result); setLoading(false) }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(String(err)))
+          setLoading(false)
+        }
+      })
+    return () => { cancelled = true }
+  }, [entry, routeDef.loader])
+
+  if (error && routeDef.errorComponent) {
+    return createElement(routeDef.errorComponent, { error })
+  }
+
+  if (error) {
+    return null
+  }
+
+  if (loading) {
+    return routeDef.pendingComponent ? createElement(routeDef.pendingComponent) : null
+  }
+
+  return <RouteDataProvider data={data}>{children}</RouteDataProvider>
+}
+
+// Outlet component
+
+export function Outlet() {
+  const router = useRouterInstance()
+  const stack = useRouterStack()
+  const depth = useContext(OutletDepthContext)
+
+  const topEntry = stack[stack.length - 1]
+  if (!topEntry) return null
+
+  const routeDef = router.getRouteDefinition(topEntry.routeId)
+  if (!routeDef) return null
+
+  const chain = getRouteChain(
+    { get: (id: string) => router.getRouteDefinition(id) },
+    topEntry.routeId,
+  )
+
+  const routeAtDepth = chain[depth]
+  if (!routeAtDepth) return null
+
+  const isTopOfStack = depth === chain.length - 1
+
+  const content = (
+    <StackEntryIndexContext value={stack.length - 1}>
+      <OutletDepthContext value={depth + 1}>
+        <ScreenFocusProvider active={isTopOfStack}>
+          {createElement(routeAtDepth.component)}
+        </ScreenFocusProvider>
+      </OutletDepthContext>
+    </StackEntryIndexContext>
+  )
+
+  if (routeAtDepth.loader) {
+    return (
+      <RouteRenderer entry={topEntry} routeDef={routeAtDepth}>
+        {content}
+      </RouteRenderer>
+    )
+  }
+
+  return content
+}

package/src/stack.ts

@@ -0,0 +1,27 @@
+import type { RouterState, RouterAction } from "./types.js"
+
+export function stackReducer(state: RouterState, action: RouterAction): RouterState {
+  switch (action.type) {
+    case "push":
+      return {
+        stack: [
+          ...state.stack,
+          { routeId: action.routeId, params: action.params ?? {} },
+        ],
+      }
+    case "pop":
+      if (state.stack.length <= 1) return state
+      return { stack: state.stack.slice(0, -1) }
+    case "replace":
+      return {
+        stack: [
+          ...state.stack.slice(0, -1),
+          { routeId: action.routeId, params: action.params ?? {} },
+        ],
+      }
+    case "reset":
+      return {
+        stack: [{ routeId: action.routeId, params: action.params ?? {} }],
+      }
+  }
+}

package/src/state-cache.ts

@@ -0,0 +1,19 @@
+export class StateCache {
+  private cache = new Map<string, unknown>()
+
+  save(key: string, state: unknown): void {
+    this.cache.set(key, state)
+  }
+
+  restore<T>(key: string): T | undefined {
+    return this.cache.get(key) as T | undefined
+  }
+
+  clear(key: string): void {
+    this.cache.delete(key)
+  }
+
+  clearAll(): void {
+    this.cache.clear()
+  }
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+import type React from "react"
+import type { StateCache } from "./state-cache.js"
+
+export interface RouteDefinition<TParams = Record<string, unknown>> {
+  id: string
+  parent?: RouteDefinition
+  component: React.ComponentType
+  title?: string | ((opts: { params: TParams }) => string)
+  loader?: (opts: { params: TParams }) => Promise<unknown>
+  pendingComponent?: React.ComponentType
+  errorComponent?: React.ComponentType<{ error: Error }>
+}
+
+export interface StackEntry {
+  routeId: string
+  params: Record<string, unknown>
+}
+
+export interface RouterState {
+  stack: StackEntry[]
+}
+
+export type RouterAction =
+  | { type: "push"; routeId: string; params?: Record<string, unknown> }
+  | { type: "pop" }
+  | { type: "replace"; routeId: string; params?: Record<string, unknown> }
+  | { type: "reset"; routeId: string; params?: Record<string, unknown> }
+
+export interface RouterOptions {
+  routes: RouteDefinition[]
+  defaultRoute: string
+  initialParams?: Record<string, unknown>
+}
+
+export interface RouterInstance {
+  push(routeId: string, params?: Record<string, unknown>): void
+  pop(): void
+  replace(routeId: string, params?: Record<string, unknown>): void
+  reset(routeId: string, params?: Record<string, unknown>): void
+  canGoBack(): boolean
+  readonly currentRoute: StackEntry
+  readonly stack: readonly StackEntry[]
+  readonly stateCache: StateCache
+  subscribe(listener: () => void): () => void
+  getRouteDefinition(routeId: string): RouteDefinition | undefined
+}