@solidrt/router 0.0.62

package/src/router.tsx

@@ -0,0 +1,450 @@
+// The Solid binding over route.ts and stack.ts: the state in a signal, the
+// navigation, the back step, blocking, links in and the location out, the
+// JSX tree (`<Route>`) and the components that render the matched routes.
+// Everything here is built on what core offers every app (onBack, onLink,
+// env.launchLink, reportLocation from srt:dev); core knows nothing of routes.
+import { createSignal, createMemo, createContext, createEffect, useContext, untrack, onCleanup, children, Show, For } from "@solidrt/core"
+import { env, onBack, onLink } from "@solidrt/core"
+import { reportLocation } from "srt:dev"
+import { createRootRoute, createRoute, formatPath, linkToPath, matchPath, place } from "./route"
+import type { AnyRoute, Match, ParamsOf, RawParams, Route as RouteValue } from "./route"
+import { back as stepBack, changed, currentPath, findTabs, initialState, push, replace, reset, resolve } from "./stack"
+import type { Entries, NavState, TabsInfo } from "./stack"
+
+/** The route value (see route.ts); `Route` the component is the JSX form. */
+export type Route<P = {}> = RouteValue<P>
+
+/** Where the app is: the top of the stack, matched. */
+export interface Location {
+  /** The path, root-first with params filled in; the stack's own currency. */
+  path: string
+  /** The matched routes root-first; the last is the screen. */
+  matches: Match[]
+}
+
+/**
+ * A navigation target: a path (as a link or a tool would give it), a route
+ * with no params, or a route with the params its pattern needs. The route
+ * forms are checked at compile time; the path form is matched at run time.
+ */
+export type NavTarget<R extends AnyRoute = AnyRoute> = string | Route<{}> | { route: R; params: ParamsOf<R> }
+
+export interface NavigateOptions {
+  /** Swap the current entry instead of pushing over it. */
+  replace?: boolean
+  /**
+   * Start the stack over at this entry: the app's home after a flow is
+   * finished (a scan dialed, a login done), where back should leave the app
+   * rather than revisit the flow. With tabs, every tab returns to its root.
+   */
+  reset?: boolean
+}
+
+/**
+ * A guard on leaving the current entry: false keeps the app where it is;
+ * true, or a promise resolving to true, lets the navigation through. The
+ * promise form holds it while the user answers a dialog.
+ */
+export type Blocker = () => boolean | Promise<boolean>
+
+export interface RouterOptions {
+  /** The root of the route tree (createRootRoute). */
+  tree: AnyRoute
+  /**
+   * Where the app starts: a path, or a saved `entries()` to resume with. A
+   * launch link (env.launchLink) wins over it: the user just asked for that
+   * screen. Defaults to "/".
+   */
+  initial?: string | Entries
+}
+
+/** The tabs of a tabs route, from `useTabs()`. */
+export interface Tabs {
+  /** The tabs' root paths, in declaration order; the first is home. */
+  paths: string[]
+  /** The tab that shows, as its root path. Reactive. */
+  active(): string
+  /**
+   * Show a tab: another tab as it was left, the active one back at its
+   * root. Resolves false when a blocker held it.
+   */
+  select(path: string): Promise<boolean>
+}
+
+export interface Router {
+  /**
+   * The stack as plain data, bottom first: an array of paths, or with
+   * tabs the parent stack and the tabs. Save it in onSuspend. Reactive.
+   */
+  entries(): Entries
+  /** The matched top of the stack, or null when nothing matches. Reactive. */
+  location(): Location | null
+  /**
+   * Push a target onto the stack (or replace the top, or reset to it).
+   * Returns false, and warns, when no route matches; a blocker may cancel it
+   * later, which the returned promise reports.
+   */
+  navigate(target: NavTarget, options?: NavigateOptions): Promise<boolean>
+  /** Pop the stack. Resolves false at the root (nothing to pop) or when blocked. */
+  back(): Promise<boolean>
+  /** The path a target names; what a link to it would carry. */
+  href(target: NavTarget): string
+  /** @internal the state as stack.ts sees it */
+  state(): NavState
+  /** @internal the tree's tabs route, or null */
+  tabs: TabsInfo | null
+  /** @internal the tab that shows, or null without tabs */
+  activeTab(): string | null
+  /** @internal a tab's own location: the top of its stack, matched */
+  tabLocation(tab: string): () => Location | null
+  /** @internal the blockers registered by useBlocker, per scope (null: the parent stack) */
+  blockers: Map<string | null, Set<Blocker>>
+  /** @internal the tree */
+  tree: AnyRoute
+}
+
+/**
+ * The router's state, created once per app (at module scope or in the app
+ * component) and rendered by `<Router router={...}>`. Navigation is a
+ * signal write, so Solid's transition semantics apply: a screen whose async
+ * reads are pending keeps the previous one on screen, `isPending(() =>
+ * router.location()` says so.
+ */
+export function createRouter(options: RouterOptions): Router {
+  let tree = options.tree
+  let tabs = findTabs(tree)
+  let launch = env.launchLink
+  let [state, setState] = createSignal<NavState>(
+    initialState(tree, tabs, launch != null ? launch : options.initial, linkToPath),
+  )
+  let located = (path: string | undefined): Location | null => {
+    if (path === undefined) return null
+    let matches = matchPath(tree, path)
+    return matches ? { path, matches } : null
+  }
+  let location = createMemo<Location | null>(() => located(currentPath(state(), tabs)))
+  let tabLocations = new Map<string, () => Location | null>()
+  for (let root of tabs?.roots ?? []) {
+    tabLocations.set(
+      root,
+      createMemo<Location | null>(() => {
+        let stack = state().tabs?.stacks[root]
+        return located(stack?.[stack.length - 1])
+      }),
+    )
+  }
+  let blockers = new Map<string | null, Set<Blocker>>()
+
+  let href = (target: NavTarget): string => {
+    if (typeof target === "string") return linkToPath(target)
+    if ("route" in target) return formatPath(target.route, target.params as Record<string, unknown>)
+    return formatPath(target)
+  }
+
+  // Runs the blockers of the given scopes; a sync false cancels at once,
+  // promises are awaited together and any false cancels.
+  let allowed = async (scopes: Array<string | null>): Promise<boolean> => {
+    let pending: Promise<boolean>[] = []
+    for (let scope of scopes) {
+      for (let block of blockers.get(scope) ?? []) {
+        let verdict = block()
+        if (verdict === false) return false
+        if (verdict !== true) pending.push(verdict)
+      }
+    }
+    if (pending.length === 0) return true
+    return (await Promise.all(pending)).every(Boolean)
+  }
+
+  let router: Router = {
+    entries: () => {
+      let s = state()
+      return s.tabs ? { stack: s.stack, tabs: s.tabs } : s.stack
+    },
+    location,
+    href,
+    state,
+    tabs,
+    activeTab: () => state().tabs?.active ?? null,
+    tabLocation: (tab) => tabLocations.get(tab) ?? (() => null),
+    blockers,
+    tree,
+    async navigate(target, options = {}) {
+      let path = href(target)
+      let to = resolve(tree, tabs, path)
+      if (!to) {
+        console.warn(`Router: no route matches "${path}"`)
+        return false
+      }
+      let apply = (s: NavState) => (options.reset ? reset(tabs, to) : options.replace ? replace(s, tabs, to) : push(s, tabs, to))
+      // The blockers asked are those of the stacks the move changes; the
+      // state is read again after they answer, in case it moved meanwhile.
+      let before = untrack(state)
+      if (!(await allowed(changed(before, apply(before))))) return false
+      setState((s) => apply(s))
+      return true
+    },
+    async back() {
+      let before = untrack(state)
+      let next = stepBack(before, tabs)
+      if (!next) return false
+      if (!(await allowed(changed(before, next)))) return false
+      setState((s) => stepBack(s, tabs) ?? s)
+      return true
+    },
+  }
+  return router
+}
+
+const RouterContext = createContext<Router>()
+// How deep in the matched chain the surrounding route is; an Outlet renders
+// the next one.
+const DepthContext = createContext<number>(0)
+// The location a subtree renders from: the app's, or inside a tab that
+// tab's own, so a hidden tab keeps its params and screen while another
+// shows. `tab` is the blocker scope.
+interface Scope {
+  location: () => Location | null
+  tab: string | null
+}
+const ScopeContext = createContext<Scope>()
+
+export type RouterProps =
+  /** A router made with createRouter, over a tree of route values. */
+  | { router: Router; initial?: never; children?: never }
+  /**
+   * A tree of `<Route>` elements, in matching order, under a root with no
+   * component; the router is made here and reached through the hooks.
+   */
+  | { router?: never; initial?: string | Entries; children: any }
+
+/**
+ * Renders the matched routes and owns the app's step of the back stack, the
+ * links in and the location out. Mount it once, inside the window. Its
+ * `onBack` registers first, so every screen and dialog above it gets the
+ * event before the stack pops.
+ */
+export function Router(props: RouterProps) {
+  let router = untrack(
+    () =>
+      props.router ??
+      createRouter({ tree: createRootRoute({ children: routesOf(props.children) }), initial: props.initial }),
+  )
+
+  onBack((e) => {
+    // Nothing to pop at the root: the platform's default (background on
+    // Android, exit elsewhere) runs unless something above prevented it.
+    if (stepBack(untrack(router.state), router.tabs) === null) return
+    e.preventDefault()
+    void router.back()
+  })
+  onLink((link) => {
+    void router.navigate(linkToPath(link))
+  })
+  // The location out: tooling reads it, and a hot reload re-enters it.
+  createEffect(
+    () => router.location()?.path ?? null,
+    (path) => reportLocation(path),
+  )
+  onCleanup(() => reportLocation(null))
+
+  return (
+    <RouterContext value={router}>
+      <ScopeContext value={{ location: router.location, tab: null }}>
+        <RouteView depth={0} />
+      </ScopeContext>
+    </RouterContext>
+  )
+}
+
+export interface RouteProps {
+  /** This route's own path below its parent (see createRoute); `/` without one. */
+  path?: string
+  /** What renders here; without one, an outlet alone. */
+  component?: () => any
+  /** Each child is a tab with a stack of its own (see createRoute). */
+  tabs?: boolean
+  /**
+   * A route value to place here instead: typed or validated params live on
+   * the value (createRoute), the JSX gives it its place in the tree. Not
+   * with `path`, `component` or `tabs`.
+   */
+  route?: AnyRoute
+  /** Nested `<Route>` elements, in matching order. */
+  children?: any
+}
+
+/**
+ * One route of a JSX tree, under `<Router>` or another `<Route>`. Not an
+ * element: it evaluates to a route value that its parent places.
+ */
+export function Route(props: RouteProps): any {
+  return untrack(() => {
+    let below = routesOf(props.children)
+    if (props.route) {
+      if (props.path !== undefined || props.component !== undefined || props.tabs !== undefined) {
+        throw new Error("<Route route={...}> takes no path, component or tabs: they are the route's own")
+      }
+      place(props.route, below)
+      return props.route
+    }
+    return createRoute({ path: props.path ?? "/", component: props.component, tabs: props.tabs, children: below })
+  })
+}
+
+// The route values a `children` slot holds, resolved once; anything else
+// there is a mistake (a `<Route>` is not an element and cannot mix with
+// them).
+function routesOf(slot: any): AnyRoute[] {
+  let list = children(() => slot).toArray()
+  for (let item of list) {
+    if (typeof item !== "object" || item === null || !("segments" in item)) {
+      throw new Error("<Router> and <Route> take only <Route> elements as children")
+    }
+  }
+  return list as unknown as AnyRoute[]
+}
+
+// The route at `depth` of the scope's match chain. Keyed on the route, not
+// the match: params changing under the same route update reactively through
+// useParams, without a remount. The tabs route is the exception: once
+// mounted at its depth it stays, hidden while another route shows there (a
+// full-window screen over the tab bar), so the tabs keep their state.
+function RouteView(props: { depth: number }) {
+  let router = useContext(RouterContext)
+  let scope = useContext(ScopeContext)
+  let route = createMemo(() => scope.location()?.matches[props.depth]?.route ?? null)
+  let tabsRoute = router.tabs?.route ?? null
+  let tabsSeen = createMemo(() => tabsRoute !== null && route() === tabsRoute)
+  let seen = false
+  let tabsMounted = createMemo(() => (seen ||= tabsSeen()))
+  let render = (r: AnyRoute) => (r.component ? <r.component /> : <Outlet />)
+  return (
+    <DepthContext value={props.depth}>
+      <Show when={tabsMounted()}>
+        <view flex={1} flexDirection="column" display={tabsSeen() ? "flex" : "none"}>
+          {render(tabsRoute!)}
+        </view>
+      </Show>
+      <Show when={tabsSeen() ? null : route()} keyed>
+        {render}
+      </Show>
+    </DepthContext>
+  )
+}
+
+/**
+ * Where a layout route's matched child renders. Under the tabs route it
+ * holds every tab visited so far, each in its own full-size view, the
+ * inactive ones hidden.
+ */
+export function Outlet() {
+  let router = useContext(RouterContext)
+  let depth = useContext(DepthContext)
+  let scope = useContext(ScopeContext)
+  let here = untrack(() => scope.location()?.matches[depth]?.route ?? null)
+  if (here !== null && here === router.tabs?.route) return <TabsOutlet depth={depth} />
+  return <RouteView depth={depth + 1} />
+}
+
+// The tabs under the tabs route at `depth`: mounted on first visit, kept
+// after, hidden while inactive. A hidden tab is laid out to nothing, so it
+// is never painted, hit or focused; its reactive code keeps running.
+function TabsOutlet(props: { depth: number }) {
+  let router = useContext(RouterContext)
+  let seen: string[] = []
+  let visited = createMemo(() => {
+    let active = router.activeTab()
+    if (active !== null && !seen.includes(active)) seen = [...seen, active]
+    return seen
+  })
+  return (
+    <For each={visited()}>
+      {(tab: string) => (
+        <view flex={1} flexDirection="column" display={router.activeTab() === tab ? "flex" : "none"}>
+          <ScopeContext value={{ location: router.tabLocation(tab), tab }}>
+            <RouteView depth={props.depth + 1} />
+          </ScopeContext>
+        </view>
+      )}
+    </For>
+  )
+}
+
+/** The router this component renders under. */
+export function useRouter(): Router {
+  return useContext(RouterContext)
+}
+
+/**
+ * The current location, reactive; null when nothing matches. Inside a tab
+ * it is that tab's own, whether or not the tab shows.
+ */
+export function useLocation(): () => Location | null {
+  return useContext(ScopeContext).location
+}
+
+/**
+ * The params of the current location. With a route (the one this component
+ * renders at, or an ancestor) they are typed by it; without one they are
+ * the screen's raw strings, as a JSX `<Route path>` carries them. Reactive:
+ * a navigation to the same route with other params updates it in place.
+ */
+export function useParams(): () => RawParams
+export function useParams<R extends AnyRoute>(route: R): () => ParamsOf<R>
+export function useParams(route?: AnyRoute): () => any {
+  let scope = useContext(ScopeContext)
+  return createMemo(() => {
+    let matches = scope.location()?.matches ?? []
+    let match = (route && matches.find((m) => m.route === route)) ?? matches[matches.length - 1]
+    return match?.params ?? {}
+  })
+}
+
+/** `navigate` bound to the router this component renders under. */
+export function useNavigate(): (target: NavTarget, options?: NavigateOptions) => Promise<boolean> {
+  let router = useContext(RouterContext)
+  return (target, options) => router.navigate(target, options)
+}
+
+/**
+ * The tabs of the tree's tabs route, for the component that draws the tab
+ * bar (and for a screen to learn whether its tab shows). Throws without a
+ * tabs route.
+ */
+export function useTabs(): Tabs {
+  let router = useContext(RouterContext)
+  let tabs = router.tabs
+  if (!tabs) throw new Error("useTabs: the route tree has no tabs route")
+  return {
+    paths: tabs.roots,
+    active: () => router.activeTab() ?? tabs.roots[0]!,
+    select: (path) => router.navigate(path),
+  }
+}
+
+/**
+ * A link: its path (for display or a tool) and a `go()` for a press handler.
+ * Styling is the caller's; a components Link wraps it.
+ */
+export function createLink(target: NavTarget, options?: NavigateOptions): { href: string; go: () => Promise<boolean> } {
+  let router = useContext(RouterContext)
+  return { href: router.href(target), go: () => router.navigate(target, options) }
+}
+
+/**
+ * Guards leaving the current entry while this component is mounted: back,
+ * navigate and replace ask `block` first when they change the stack this
+ * component is in (a tab's own, or the parent stack). Return false to stay,
+ * true to go, or a promise (a confirm dialog) that decides later. A
+ * blocked back is prevented, so it never falls through to the platform
+ * default. Showing another tab changes no stack, so it asks no blocker.
+ */
+export function useBlocker(block: Blocker): void {
+  let router = useContext(RouterContext)
+  let scope = useContext(ScopeContext).tab
+  let set = router.blockers.get(scope)
+  if (!set) router.blockers.set(scope, (set = new Set()))
+  set.add(block)
+  onCleanup(() => set.delete(block))
+}

package/src/stack.ts

@@ -0,0 +1,249 @@
+// The navigation state and its transitions, headless: a parent stack, and
+// with a tabs route in the tree a stack per tab under it. Plain functions
+// over plain data, no signals; router.tsx keeps the state in a signal and
+// applies these. Tested under bun without a client (tests/).
+//
+// Without tabs the state is the one stack of paths it always was. With
+// tabs, the parent stack holds the full-window screens and one marker
+// entry, the tabs route's own path, that stands for the tab bar screen;
+// which tab shows and what each tab has pushed is in `tabs`. This is the
+// navigator tree every native router keeps (a root stack, tabs, a stack per
+// tab), written as data.
+import { formatPath, formatPattern, matchPath, tabsRoutes } from "./route"
+import type { AnyRoute, Match } from "./route"
+
+export interface TabsState {
+  /** The tab that shows: its root path. */
+  active: string
+  /** Each tab's stack, bottom first; the bottom is always the tab's root. */
+  stacks: Record<string, string[]>
+}
+
+export interface NavState {
+  /** The parent stack, bottom first; `tabs.path` in it is the tab bar screen. */
+  stack: string[]
+  tabs: TabsState | null
+}
+
+/**
+ * The stack as plain data: an array of paths without tabs, the parent stack
+ * plus the tabs with them. What `entries()` returns and `initial` takes.
+ */
+export type Entries = string[] | { stack: string[]; tabs: TabsState }
+
+/** The tree's tabs route, resolved once. */
+export interface TabsInfo {
+  route: AnyRoute
+  /** The route's own path: the parent-stack entry that stands for the tab bar. */
+  path: string
+  /** The tabs' root paths, in declaration order; the first is home. */
+  roots: string[]
+}
+
+export function findTabs(root: AnyRoute): TabsInfo | null {
+  let found = tabsRoutes(root)
+  if (found.length === 0) return null
+  if (found.length > 1) {
+    throw new Error(`Router: one tabs route per tree ("${formatPattern(found[0]!)}" and "${formatPattern(found[1]!)}")`)
+  }
+  let route = found[0]!
+  return { route, path: formatPath(route), roots: route.children.map((tab) => formatPath(tab)) }
+}
+
+/** A path resolved against the tree: where it lands. */
+export interface Target {
+  path: string
+  matches: Match[]
+  /** The tab it falls under (its root path), or null for the parent stack. */
+  tab: string | null
+}
+
+/**
+ * Where `path` lands, or null when nothing matches. A path that names the
+ * tabs route itself, with no tab under it, lands on the first tab's root.
+ */
+export function resolve(tree: AnyRoute, tabs: TabsInfo | null, path: string): Target | null {
+  let matches = matchPath(tree, path)
+  if (!matches) return null
+  if (!tabs) return { path, matches, tab: null }
+  let at = matches.findIndex((m) => m.route === tabs.route)
+  if (at < 0) return { path, matches, tab: null }
+  let tab = matches[at + 1]
+  if (!tab) return resolve(tree, tabs, tabs.roots[0]!)
+  return { path, matches, tab: formatPath(tab.route) }
+}
+
+// Every tab on its root, `active` showing.
+function allRoots(tabs: TabsInfo, active: string): TabsState {
+  let stacks: Record<string, string[]> = {}
+  for (let root of tabs.roots) stacks[root] = [root]
+  return { active, stacks }
+}
+
+// The parent stack with the tab bar on top: cut back to the marker when it
+// is there (the screens above it leave), appended when it is not. The same
+// array when it already is on top.
+function showTabs(stack: string[], marker: string): string[] {
+  let at = stack.lastIndexOf(marker)
+  if (at === stack.length - 1) return stack
+  return at >= 0 ? stack.slice(0, at + 1) : [...stack, marker]
+}
+
+// `state` with tab `tab` showing and its stack replaced.
+function withTab(state: NavState, tabs: TabsInfo, tab: string, stack: string[]): NavState {
+  let current = state.tabs ?? allRoots(tabs, tab)
+  let same = current.stacks[tab] === stack
+  return {
+    stack: showTabs(state.stack, tabs.path),
+    tabs: { active: tab, stacks: same ? current.stacks : { ...current.stacks, [tab]: stack } },
+  }
+}
+
+// A tab's root as a target is the tab bar's tap: a tab that does not show
+// is shown as it was left, the one that shows goes back to its root. The
+// stack for the target's tab, or null when the target is a deeper screen.
+function toRoot(state: NavState, tabs: TabsInfo, target: Target): string[] | null {
+  if (target.path !== target.tab) return null
+  let current = state.tabs?.stacks[target.tab!] ?? [target.tab!]
+  let showing = state.tabs?.active === target.tab && state.stack[state.stack.length - 1] === tabs.path
+  return showing && current.length > 1 ? [target.tab!] : current
+}
+
+/** `target` pushed: onto the parent stack, or onto its tab, which then shows. */
+export function push(state: NavState, tabs: TabsInfo | null, target: Target): NavState {
+  if (!tabs || target.tab === null) return { ...state, stack: [...state.stack, target.path] }
+  let current = state.tabs?.stacks[target.tab] ?? [target.tab]
+  return withTab(state, tabs, target.tab, toRoot(state, tabs, target) ?? [...current, target.path])
+}
+
+/**
+ * `target` swapped for the top of the stack that holds it: the parent
+ * stack's top for a full-window screen (the tab bar itself when that is
+ * showing), the tab's top for a screen in a tab, which then shows. A tab's
+ * root is never swapped out, and a tab's root as the target is a tap on
+ * its tab, as for push.
+ */
+export function replace(state: NavState, tabs: TabsInfo | null, target: Target): NavState {
+  if (!tabs || target.tab === null) return { ...state, stack: [...state.stack.slice(0, -1), target.path] }
+  let current = state.tabs?.stacks[target.tab] ?? [target.tab]
+  let next =
+    toRoot(state, tabs, target) ?? (current.length > 1 ? [...current.slice(0, -1), target.path] : [target.tab, target.path])
+  return withTab(state, tabs, target.tab, next)
+}
+
+/**
+ * The state started over at `target`: every tab on its root, and the
+ * target's tab root beneath it when it is in a tab. A full-window target
+ * stands alone, so back leaves the app (a flow that ends outside the tabs).
+ */
+export function reset(tabs: TabsInfo | null, target: Target): NavState {
+  if (!tabs) return { stack: [target.path], tabs: null }
+  if (target.tab === null) return { stack: [target.path], tabs: allRoots(tabs, tabs.roots[0]!) }
+  let all = allRoots(tabs, target.tab)
+  all.stacks[target.tab] = target.path === target.tab ? [target.tab] : [target.tab, target.path]
+  return { stack: [tabs.path], tabs: all }
+}
+
+/**
+ * One step back: the tab bar showing pops its active tab, or switches a
+ * non-first tab at its root to the first; otherwise the parent stack pops.
+ * Null when there is nothing to pop.
+ */
+export function back(state: NavState, tabs: TabsInfo | null): NavState | null {
+  if (tabs && state.tabs && state.stack[state.stack.length - 1] === tabs.path) {
+    let active = state.tabs.active
+    let current = state.tabs.stacks[active] ?? [active]
+    if (current.length > 1) return withTab(state, tabs, active, current.slice(0, -1))
+    if (active !== tabs.roots[0]) return { ...state, tabs: { ...state.tabs, active: tabs.roots[0]! } }
+  }
+  if (state.stack.length > 1) return { ...state, stack: state.stack.slice(0, -1) }
+  return null
+}
+
+/** The path that shows: the parent stack's top, or the active tab's. */
+export function currentPath(state: NavState, tabs: TabsInfo | null): string | undefined {
+  let top = state.stack[state.stack.length - 1]
+  if (tabs && state.tabs && top === tabs.path) {
+    let stack = state.tabs.stacks[state.tabs.active]
+    return stack?.[stack.length - 1]
+  }
+  return top
+}
+
+/**
+ * The scopes whose stacks `next` changes from `prev`: null for the parent
+ * stack, a tab's root for its stack. What a navigation leaves, so whose
+ * blockers it asks; a bare tab switch changes no stack and asks none.
+ */
+export function changed(prev: NavState, next: NavState): Array<string | null> {
+  let out: Array<string | null> = []
+  if (prev.stack !== next.stack) out.push(null)
+  if (prev.tabs && next.tabs && prev.tabs.stacks !== next.tabs.stacks) {
+    for (let tab of Object.keys(next.tabs.stacks)) {
+      if (prev.tabs.stacks[tab] !== next.tabs.stacks[tab]) out.push(tab)
+    }
+  }
+  return out
+}
+
+/**
+ * The state `initial` names, or the launch link's. A path lands where a
+ * push from nothing would, a tab's root beneath a screen in a tab; a list
+ * of paths is pushed in order; an `entries()` object is taken as saved
+ * when every entry still fits the tree, and not at all otherwise (what
+ * the app should show instead is the app's call, not a repair). Paths
+ * that match nothing are dropped with a warning, and with nothing left
+ * the app starts at "/".
+ */
+export function initialState(
+  tree: AnyRoute,
+  tabs: TabsInfo | null,
+  initial: string | Entries | undefined,
+  normalize: (path: string) => string,
+): NavState {
+  let target = (path: string): Target | null => {
+    let t = resolve(tree, tabs, normalize(path))
+    if (!t) console.warn(`Router: no route matches "${path}"; dropped from the initial stack`)
+    return t
+  }
+  if (initial !== undefined && !Array.isArray(initial) && typeof initial !== "string") {
+    if (fits(tree, tabs, initial, normalize)) return { stack: initial.stack, tabs: tabs ? initial.tabs : null }
+    initial = undefined
+  }
+  let paths = initial === undefined ? ["/"] : typeof initial === "string" ? [initial] : initial
+  let state: NavState | null = null
+  for (let path of paths) {
+    let t = target(path)
+    if (!t) continue
+    state = state ? push(state, tabs, t) : reset(tabs, t)
+  }
+  return state ?? { stack: ["/"], tabs: tabs ? allRoots(tabs, tabs.roots[0]!) : null }
+}
+
+// Whether a saved `entries()` object still describes this tree: a parent
+// entry is the tabs marker or lands outside the tabs, every tab is there
+// with its root at the bottom and its entries landing in it, and `active`
+// is a tab. The first misfit is named in a warning.
+function fits(
+  tree: AnyRoute,
+  tabs: TabsInfo | null,
+  saved: { stack: string[]; tabs: TabsState },
+  normalize: (path: string) => string,
+): boolean {
+  let misfit = (what: string): false => {
+    console.warn(`Router: the saved stack does not fit the route tree (${what}); not resumed`)
+    return false
+  }
+  let lands = (path: string, tab: string | null) => resolve(tree, tabs, normalize(path))?.tab === tab
+  for (let path of saved.stack) {
+    if (!(tabs && path === tabs.path) && !lands(path, null)) return misfit(`"${path}"`)
+  }
+  if (!tabs) return saved.stack.length > 0 || misfit("empty")
+  if (!tabs.roots.includes(saved.tabs.active)) return misfit(`active tab "${saved.tabs.active}"`)
+  for (let root of tabs.roots) {
+    let entries = saved.tabs.stacks[root]
+    if (!entries || entries[0] !== root) return misfit(`tab "${root}"`)
+    for (let path of entries) if (!lands(path, root)) return misfit(`"${path}" in tab "${root}"`)
+  }
+  return saved.stack.length > 0 || misfit("empty")
+}