@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/src/api/linking/linking.ts

@@ -0,0 +1,242 @@
+import { Linking, Platform } from 'react-native';
+import { getLaunchLink } from '../../engine/native';
+import type { LayoutRoot } from '../../interfaces/Layout';
+import { resolveRoot, type RootsMap } from '../app/roots';
+import { commandsStarted, whenCommandsSettle } from '../commands/errors';
+import { getAppContext, subscribeAppContext } from '../context/appContext';
+import { buildRoot, type RootLayout } from '../layout/Root';
+import { navigation } from '../navigation';
+import { getNavigationState, whenScreenAfter, type NavigationState } from '../state/navigationState';
+import {
+  compileRoutes,
+  matchLink,
+  parseLink,
+  type CompiledRoute,
+  type LinkMatch,
+} from './linkPaths';
+import { getPendingLink, setPendingLink, setPendingLinkOpener } from './pendingLinks';
+import type { LinkInfo, LinkingConfig } from './types';
+
+// The links of the app: the one that launched it, which can make the first root, and those that come while it runs.
+// A link runs once the first root is shown and the native side told which screen shows, so its commands act from
+// there; one whose `when` is false waits as the pending link. What the app's callbacks throw goes to `onError`.
+
+type Route =
+  | string
+  | ((params: Record<string, string>, link: LinkInfo) => unknown)
+  | {
+      start?: (params: Record<string, string>, link: LinkInfo) => unknown;
+      open?: (params: Record<string, string>, link: LinkInfo) => unknown;
+      when?: (context: unknown) => boolean;
+    };
+
+// The routes as the app wrote them; each is read as a `Route`.
+type Config = Omit<LinkingConfig<any, any, string, any>, 'routes'> & { routes: object };
+
+let config: Config | undefined;
+let roots: RootsMap | undefined;
+let routes: CompiledRoute[] = [];
+let onError: ((error: unknown, url: string) => void) | undefined;
+// The links run at once. Before, they wait in `early`.
+let started = false;
+const early: { link: LinkMatch; initial: boolean }[] = [];
+// The launch URL as the native side gave it, and matched: kept for every try of the first start.
+let launchUrl: Promise<string | null> | undefined;
+let launch: Promise<LinkMatch | undefined> | undefined;
+let pendingCheck = false;
+// The links whose `when` threw, reported once each.
+const whenFailed = new Set<string>();
+
+/** Starts the links of the app, once per JavaScript runtime. */
+export function setupLinking(
+  linking: Config,
+  options: {
+    roots: RootsMap | undefined;
+    onError: ((error: unknown, url: string) => void) | undefined;
+  }
+): void {
+  config = linking;
+  roots = options.roots;
+  onError = options.onError;
+  // On iOS the first React content to appear sends the waiting links to Linking as `url` events; asked now, before
+  // a warning can show LogBox, the launch link stays for the first root. Android reads it from the activity, which
+  // is there once the native side launched.
+  if (Platform.OS === 'ios') takeLaunchUrl();
+  routes = compileRoutes(Object.keys(linking.routes));
+  Linking.addEventListener('url', ({ url }) => receive(url));
+  subscribeAppContext(openPendingWhenAllowed);
+  setPendingLinkOpener((link) => run(link, routeOf(link), false));
+}
+
+/**
+ * The link that launched the app, matched as the app starts (`unmatched` may run commands then); the same one for
+ * every try of the first start.
+ */
+export function launchLink(): Promise<LinkMatch | undefined> {
+  launch ??= takeLaunchUrl().then((url) => (url ? find(url) : undefined));
+  return launch;
+}
+
+function takeLaunchUrl(): Promise<string | null> {
+  // A link the native side can't read (a broken intent of another app) is no link: the start goes on.
+  launchUrl ??= config ? getLaunchLink().catch(() => null) : Promise.resolve(null);
+  return launchUrl;
+}
+
+/**
+ * The first root the launch link makes with `start`, when its route has one and may run now. `handled`: the link
+ * needs nothing more — it made the root, or its `start` failed and went to `onError`.
+ */
+export function launchRoot(link: LinkMatch | undefined): { root?: LayoutRoot; handled: boolean } {
+  if (!link) return { handled: false };
+  const route = routeOf(link);
+  if (typeof route !== 'object' || !route.start || !allowed(route, link.url)) {
+    return { handled: false };
+  }
+  try {
+    return { root: toRoot(route.start(link.params, infoOf(link, true))), handled: true };
+  } catch (error) {
+    report(error, link.url);
+    return { handled: true };
+  }
+}
+
+/** A link that failed outside its route: the native side couldn't set the root its `start` made. */
+export function reportLink(error: unknown, url: string): void {
+  report(error, url);
+}
+
+/**
+ * The first root is shown: once the native side told its screen, the launch link runs unless it was handled, then the
+ * links that came meanwhile.
+ */
+export async function linksStarted(
+  link: LinkMatch | undefined,
+  handled: boolean,
+  stateBefore: NavigationState
+): Promise<void> {
+  // A first frame can take long on a slow device: the limit only keeps a lost state from holding the links.
+  await whenScreenAfter(stateBefore, 3000);
+  started = true;
+  if (link && !handled) handle(link, true);
+  early.splice(0).forEach(({ link: next, initial }) => handle(next, initial));
+}
+
+/** The native side launched again (Android: a new activity): its link runs as in a running app. */
+export async function linksRelaunched(stateBefore: NavigationState): Promise<void> {
+  const url = await getLaunchLink().catch(() => null);
+  const link = url ? find(url) : undefined;
+  if (!link) return;
+  await whenScreenAfter(stateBefore, 3000);
+  handle(link, true);
+}
+
+function receive(url: string): void {
+  const link = find(url);
+  if (!link) return;
+  if (started) handle(link, false);
+  else early.push({ link, initial: false });
+}
+
+function find(url: string): LinkMatch | undefined {
+  const parsed = parseLink(url, config?.prefixes);
+  const link = parsed && matchLink(parsed, routes);
+  if (link) return link;
+  try {
+    if (config?.unmatched) config.unmatched(url);
+    else if (__DEV__) console.warn(`[navigation] No route of linking takes '${url}'`);
+  } catch (error) {
+    report(error, url);
+  }
+  return undefined;
+}
+
+function routeOf(link: { route: string }): Route {
+  return (config!.routes as Record<string, Route>)[link.route]!;
+}
+
+// A `when` that throws keeps the link waiting; its error is reported once for the link.
+function allowed(route: Route, url: string): boolean {
+  const when = (typeof route === 'object' && route.when) || config?.when;
+  try {
+    return !when || when(getAppContext());
+  } catch (error) {
+    if (!whenFailed.has(url)) {
+      whenFailed.add(url);
+      report(error, url);
+    }
+    return false;
+  }
+}
+
+function handle(link: LinkMatch, initial: boolean): void {
+  const route = routeOf(link);
+  if (allowed(route, link.url)) {
+    run(link, route, initial);
+    return;
+  }
+  const { url, path, route: pattern, params, query } = link;
+  setPendingLink({ url, path, route: pattern, params, query });
+}
+
+/** Runs a route as in a running app: `open`, the screen pushed, or `start` shown with `switchTo`. */
+async function run(link: LinkMatch, route: Route, initial: boolean): Promise<void> {
+  const info = infoOf(link, initial);
+  try {
+    if (typeof route === 'string') {
+      await (navigation.push as (name: string, config: object) => Promise<string>)(route, {
+        props: { ...link.query, ...link.params },
+      });
+    } else if (typeof route === 'function') {
+      await route(link.params, info);
+    } else if (route.open) {
+      await route.open(link.params, info);
+    } else if (route.start) {
+      await switchToTarget(route.start(link.params, info));
+    }
+  } catch (error) {
+    report(error, link.url);
+  }
+}
+
+function switchToTarget(target: unknown): Promise<void> {
+  const switchTo = navigation.switchTo as (target: unknown, ...param: unknown[]) => Promise<void>;
+  if (Array.isArray(target)) return switchTo(target[0], ...target.slice(1));
+  return switchTo(target);
+}
+
+function toRoot(target: unknown): LayoutRoot {
+  if (typeof target === 'string') return resolveRoot(roots, target, []);
+  if (Array.isArray(target)) return resolveRoot(roots, target[0] as string, target.slice(1));
+  return buildRoot(target as RootLayout);
+}
+
+function infoOf(link: LinkMatch, initial: boolean): LinkInfo {
+  return { url: link.url, path: link.path, query: link.query, initial };
+}
+
+function report(error: unknown, url: string): void {
+  if (onError) onError(error, url);
+  else console.error(`[navigation] The link '${url}' failed`, error);
+}
+
+// A waiting link runs once the context lets it, after the commands of the same change — the `switchTo` that follows
+// `setContext` at a sign-in — and after the native side told the screen they show, so the link opens in the new root.
+function openPendingWhenAllowed(): void {
+  if (config?.pending === 'manual' || pendingCheck || !getPendingLink()) return;
+  pendingCheck = true;
+  const stateBefore = getNavigationState();
+  const commandsBefore = commandsStarted();
+  setTimeout(async () => {
+    try {
+      await whenCommandsSettle(commandsBefore);
+      if (commandsStarted() !== commandsBefore) await whenScreenAfter(stateBefore, 1000);
+    } finally {
+      pendingCheck = false;
+    }
+    const link = getPendingLink();
+    if (!link || !allowed(routeOf(link), link.url)) return;
+    setPendingLink(null);
+    run({ ...link }, routeOf(link), false);
+  }, 0);
+}

package/src/api/linking/pendingLinks.ts

@@ -0,0 +1,37 @@
+import type { PendingLink } from './types';
+
+// The link that waits for `when` of `linking`: one, the latest. The navigation and `usePendingLink` read it here; the
+// linking runs it through the opener it gives at its start.
+let pending: PendingLink | null = null;
+const listeners = new Set<() => void>();
+let opener: ((link: PendingLink) => Promise<void>) | undefined;
+
+export function getPendingLink(): PendingLink | null {
+  return pending;
+}
+
+export function setPendingLink(link: PendingLink | null): void {
+  if (pending === link) return;
+  pending = link;
+  listeners.forEach((listener) => listener());
+}
+
+export function subscribePendingLink(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function setPendingLinkOpener(open: (link: PendingLink) => Promise<void>): void {
+  opener = open;
+}
+
+/** Runs the waiting link now, whatever `when` says, and forgets it; false without one. */
+export async function openPendingLink(): Promise<boolean> {
+  const link = pending;
+  if (!link || !opener) return false;
+  setPendingLink(null);
+  await opener(link);
+  return true;
+}

package/src/api/linking/types.ts

@@ -0,0 +1,130 @@
+import type { RootLayout } from '../layout/Root';
+import type { RootsMap, RootTarget } from '../app/roots';
+import type { CheckedScreens } from '../types';
+
+/** The params of a path pattern, each a string: `'user/:userId/:tab?'` gives `{ userId: string; tab?: string }`. */
+export type LinkParams<Pattern extends string> = Simplify<
+  { [Name in RequiredParam<Segment<Pattern>>]: string } & {
+    [Name in OptionalParam<Segment<Pattern>>]?: string;
+  }
+>;
+
+type Segment<Pattern extends string> = Pattern extends `${infer Head}/${infer Rest}`
+  ? Head | Segment<Rest>
+  : Pattern;
+type RequiredParam<Part> = Part extends `:${string}?`
+  ? never
+  : Part extends `:${infer Name}`
+    ? Name
+    : never;
+type OptionalParam<Part> = Part extends `:${infer Name}?` ? Name : never;
+type Simplify<Value> = { [Key in keyof Value]: Value[Key] } & {};
+
+/** A link as a route gets it. */
+export interface LinkInfo {
+  /** The whole URL. */
+  url: string;
+  /** The path the route matched, without the prefix and the query: `user/42`. */
+  path: string;
+  /** The query string by key; a key given twice keeps its last value. */
+  query: Record<string, string>;
+  /** Whether this link launched the app, or on Android a new activity of it. */
+  initial: boolean;
+}
+
+/** What a route does in a running app: any commands. */
+export type LinkHandler<Pattern extends string> = (
+  params: LinkParams<Pattern>,
+  link: LinkInfo
+) => void;
+
+/** A route with what it does when the link launches the app, when the app runs, and when it may run. */
+export interface LinkRouteConfig<Pattern extends string, Context, Roots extends RootsMap> {
+  /**
+   * The first root when the link launches the app, in place of `root` / `initialRoot`: the screen of the link with the
+   * screens to go back to, shown at once. A layout, or a root of `roots` (its name, or `[name, param]`). In a running
+   * app, a route without `open` shows it with `navigation.switchTo`.
+   */
+  start?: (
+    params: LinkParams<Pattern>,
+    link: LinkInfo
+  ) => RootTarget<Roots> | Exclude<RootLayout, string>;
+  /**
+   * What the link does in a running app, and when it launches the app and the route has no `start`: then it runs
+   * once the first root is shown.
+   */
+  open?: LinkHandler<Pattern>;
+  /** Whether the link may run now, in place of `when` of `linking`; while it is false the link waits. */
+  when?: (context: Context) => boolean;
+}
+
+/**
+ * The screens of the app that take the params of a pattern as their props, for a route given as a screen name.
+ */
+type LinkScreen<Pattern extends string, AppScreens> = {
+  [Name in keyof AppScreens & string]: unknown extends CheckedScreens<
+    { name: Name; props: LinkParams<Pattern> },
+    AppScreens
+  >
+    ? Name
+    : never;
+}[keyof AppScreens & string];
+
+/**
+ * A route: a screen name, pushed with the params and the query as its props; a function, its `open`; or
+ * `{ start, open, when }`.
+ */
+export type LinkRoute<Pattern extends string, Context, Roots extends RootsMap, AppScreens> =
+  | NoInfer<LinkScreen<Pattern, AppScreens>>
+  | LinkHandler<Pattern>
+  | LinkRouteConfig<Pattern, Context, Roots>;
+
+/** The links that open the app's screens: custom schemes, universal links (iOS) and App Links (Android). */
+export interface LinkingConfig<
+  Context = unknown,
+  Roots extends RootsMap = RootsMap,
+  Patterns extends string = string,
+  AppScreens = Record<string, unknown>,
+> {
+  /**
+   * The starts of the URLs the app takes: `'myapp://'`, `'https://example.com'`; what follows is the path. A URL that
+   * starts with none is not the app's. Without it every URL goes: the host of an `http(s)` URL is left out, and for
+   * another scheme the path starts after `://`.
+   */
+  prefixes?: string[];
+  /**
+   * The routes by path pattern: static parts, `:param`, and `:param?` at the end. The most specific match wins: more
+   * required parts first, then a static part before a param at the same place, then fewer parts, then the order here.
+   */
+  routes: { [Pattern in Patterns]: LinkRoute<Pattern, Context, Roots, AppScreens> };
+  /**
+   * Whether a link may run now, from the app's context: `(context) => context.signedIn`. While it is false the link
+   * doesn't run and waits; the latest one waiting is kept (`navigation.getPendingLink`). A route's own `when` goes
+   * over it. Without it every link runs at once. It is asked when a link comes and, for a waiting one, on each
+   * `setContext`: a `when` that reads a store (Redux, Zustand) instead isn't asked again when the store changes, so
+   * use `pending: 'manual'` there.
+   */
+  when?: (context: Context) => boolean;
+  /**
+   * What a waiting link does once `when` lets it: `'auto'` runs it when the context changes so, after the commands then
+   * on their way (`setContext` and `switchTo` of a sign-in); `'manual'` keeps it for `navigation.openPendingLink`,
+   * which the app calls once it is ready, such as after a sign-in kept in a store. `'auto'` without it.
+   */
+  pending?: 'auto' | 'manual';
+  /** A URL no route takes, or with none of `prefixes`. Without it a warning in development. */
+  unmatched?: (url: string) => void;
+}
+
+/** A link that waits for `when` of `linking`. */
+export interface PendingLink {
+  /** The whole URL. */
+  url: string;
+  /** The path, without the prefix and the query. */
+  path: string;
+  /** The pattern of its route in `routes`. */
+  route: string;
+  /** The params of the path. */
+  params: Record<string, string>;
+  /** The query string by key. */
+  query: Record<string, string>;
+}

package/src/api/navigation.ts

@@ -0,0 +1,269 @@
+import { setRoot } from '../engine/commands';
+import { withSlots } from '../engine/slots';
+import { getActiveApp } from './app/activeApp';
+import { resolveRoot, type RootParam } from './app/roots';
+import * as commands from './commands/commands';
+import type { SplitColumn } from './commands/commands';
+import { command } from './commands/errors';
+import { closeMenu, openMenu } from './commands/sideMenus';
+import type { ColumnConfig, ModalConfig, OverlayConfig, PushConfig } from './commands/presentation';
+import {
+  type NavigationEventName,
+  type NavigationEvents,
+  onNavigationEvent,
+} from './events/navigationEvents';
+import { buildRoot, type RootLayout, type UsesOfRoot } from './layout/Root';
+import { getNavigationState, type NavigationState, whenTabShows } from './state/navigationState';
+import type { StackEntry } from './layout/Stack';
+import type { UsesOf } from './layout/element';
+import { getAppContext, setAppContext } from './context/appContext';
+import { getPendingLink, openPendingLink, setPendingLink } from './linking/pendingLinks';
+import type { PendingLink } from './linking/types';
+import {
+  type NavigationDirection,
+  type NavigationTheme,
+  setDirection,
+  setTheme,
+} from './theme/theme';
+import type {
+  CheckedScreens,
+  RegisteredContext,
+  RegisteredRoots,
+  RegisteredScreens,
+  ScreenName,
+  ShowArgs,
+} from './types';
+
+type RootName = keyof RegisteredRoots & string;
+
+/** The screens of a stack, each checked against the screens of the app. */
+export type CheckedEntries<Entries extends readonly StackEntry[]> = {
+  [Index in keyof Entries]: Entries[Index] &
+    NoInfer<CheckedScreens<UsesOf<Entries[Index]>, RegisteredScreens>>;
+};
+
+export interface AppNavigation {
+  /** Replaces the whole navigation with a root of `roots`: the modals close, the overlays stay. */
+  switchTo<Name extends RootName>(
+    name: Name,
+    ...param: RootParam<RegisteredRoots[Name]>
+  ): Promise<void>;
+  /**
+   * Replaces the whole navigation with a root of its own, such as the screens of a deep link. A screen named alone
+   * is a root name here, so it goes as `Stack('Name')`.
+   */
+  switchTo<const Layout extends Exclude<RootLayout, string>>(
+    layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>>
+  ): Promise<void>;
+  /** Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown. */
+  push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
+  /** Goes back in the stack of the screen the user sees; see `useNavigation().pop`. */
+  pop(): Promise<string>;
+  /** Goes back to a screen of its stack, by its id. */
+  popTo(screenId: string): Promise<string>;
+  /** `pop()` has a screen to go back to from the one the user sees; see `useNavigation().canPop`. Answers at once. */
+  canPop(): boolean;
+  /** The screen the user sees is in a modal or an overlay. Answers at once. */
+  canDismiss(): boolean;
+  /** Shows a column of the split view the user is in; see `useNavigation().showColumn`. */
+  showColumn(column: SplitColumn): Promise<void>;
+  /** Hides a column of the split view the user is in. */
+  hideColumn(column: SplitColumn): Promise<void>;
+  /** Opens a menu of the side menu the user is in; resolves once it is open and `getState()` shows its screen. */
+  openMenu(side: 'left' | 'right'): Promise<void>;
+  /**
+   * Closes the menu that is open; resolves once it is closed and `getState()` shows the center, so the next command
+   * acts from there.
+   */
+  closeMenu(): Promise<void>;
+  /** What the back button would do on the screen the user sees: `pop()`, or `dismiss()` of its modal. */
+  goBack(): Promise<string>;
+  /** `goBack()` has something to do. Answers at once. */
+  canGoBack(): boolean;
+  /** Goes back to the first screen of the stack of the screen the user sees. */
+  popToRoot(): Promise<string>;
+  /** Shows a screen alone in the stack of the screen the user sees, in place of its history; see `useNavigation().replace`. */
+  replace<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, PushConfig>
+  ): Promise<string>;
+  /** Replaces the screens of the stack of the screen the user sees. */
+  setStack<const Entries extends readonly StackEntry[]>(
+    ...entries: CheckedEntries<Entries>
+  ): Promise<string>;
+  /** Shows a screen in a column of the split view of the screen the user sees; see `useNavigation().showInColumn`. */
+  showInColumn<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, ColumnConfig>
+  ): Promise<string>;
+  /** Shows a screen over everything, in a stack of its own unless `stack: false`. */
+  showModal<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, ModalConfig>
+  ): Promise<string>;
+  /** Dismisses a modal by its id, or the modal a screen with this id is in. */
+  dismissModal(modalId: string): Promise<string>;
+  dismissAllModals(): Promise<string>;
+  /** Shows a screen over everything, without taking the place of any. */
+  showOverlay<Name extends ScreenName>(
+    name: Name,
+    ...args: ShowArgs<Name, OverlayConfig>
+  ): Promise<string>;
+  /**
+   * Dismisses an overlay by its id. iOS also takes the id of a screen inside the overlay; Android takes only the
+   * overlay's own id and rejects the id of a screen inside it.
+   */
+  dismissOverlay(overlayId: string): Promise<string>;
+  dismissAllOverlays(): Promise<string>;
+  /**
+   * Selects a tab of the tabs of the screen the user sees: by its index, or by the id of the tab. Resolves once the
+   * state shows it, so the next command acts in that tab. The state has the tab of the root's tabs only: in tabs over
+   * them (tabs in a modal) it resolves on the next change of the state, at the latest after 300 ms, and at once when
+   * the root's tabs show a tab with that index.
+   */
+  selectTab(tab: number | string): Promise<void>;
+  /**
+   * The badge of the tab with the id, or of the tab of the screen the user sees: a count or a short text. `null` and the
+   * number `0` take it away, so a count of unread messages goes as it is; the text `'0'` shows "0".
+   */
+  setTabBadge(badge: string | number | null, tab?: string): Promise<void>;
+  /** Changes the theme of the navigation: the screens shown take it too, `useNavigationTheme` renders again. */
+  setTheme(theme: NavigationTheme): void;
+  /**
+   * Changes the direction of the app (`direction` of createNavigation): the bars, the transitions and the swipe back
+   * follow at once, React content in the screens created after it. On iOS 15–16 a stack already shown keeps its
+   * direction (its bar, its swipe back and its transitions) until its next push; on iOS 17+ so does a stack that isn't
+   * on screen at the change (another tab, under a full-screen modal) when the app had no direction before.
+   */
+  setDirection(direction: NavigationDirection): void;
+  /** The app's context: `context` of createNavigation, as `setContext` changed it since. */
+  getContext(): RegisteredContext;
+  /** Changes the app's context: every `useAppContext` renders again. */
+  setContext(next: RegisteredContext | ((previous: RegisteredContext) => RegisteredContext)): void;
+  /**
+   * What the user sees now: the screen and the selected tab. Once a command resolves, it shows what the command did.
+   */
+  getState(): NavigationState;
+  /** The link that waits for `when` of `linking`, the latest one; null when none waits. */
+  getPendingLink(): PendingLink | null;
+  /**
+   * Runs the waiting link now, as in a running app, whatever its `when` says, and forgets it. Resolves once its route
+   * has run, with false when no link waits; a route that fails goes to `onError`.
+   */
+  openPendingLink(): Promise<boolean>;
+  /** Forgets the waiting link. */
+  clearPendingLink(): void;
+  /** Listens to an event of the navigation, outside the screens too; returns the function that stops listening. */
+  on<Name extends NavigationEventName>(
+    name: Name,
+    handler: (event: NavigationEvents[Name]) => void
+  ): () => void;
+}
+
+/** The started app; a command made while it starts comes after its first root. */
+async function startedApp() {
+  const app = getActiveApp();
+  if (!app) {
+    throw new Error(
+      '[navigation] A command before the app started: register it with AppRegistry.registerComponent'
+    );
+  }
+  await app.mounted;
+  return app;
+}
+
+function switchTo(target: RootLayout, ...param: unknown[]): Promise<void> {
+  return command('switchTo', async () => {
+    const app = await startedApp();
+    const root =
+      typeof target === 'string' ? resolveRoot(app.roots, target, param) : buildRoot(target);
+    await withSlots(() => setRoot(root));
+  });
+}
+
+/** The screen the user sees, which the stack commands outside the screens act from. */
+async function currentScreen(): Promise<string> {
+  await startedApp();
+  const screen = getNavigationState().screen;
+  if (!screen) throw new Error('[navigation] No screen shows, so there is no stack to act on');
+  return screen.id;
+}
+
+/** A check of the screen the user sees; false while none shows. */
+function seenScreen(check: (screenId: string) => boolean): boolean {
+  const screen = getNavigationState().screen;
+  return screen ? check(screen.id) : false;
+}
+
+/** A command from the screen the user sees; an error says which command it was. */
+function fromCurrent<T>(name: string, run: (screenId: string) => Promise<T>): Promise<T> {
+  return command(name, async () => run(await currentScreen()));
+}
+
+/** A command that needs no screen, only the app started: made while it starts, it comes after the first root. */
+function afterStart<T>(name: string, run: () => Promise<T>): Promise<T> {
+  return command(name, async () => {
+    await startedApp();
+    return run();
+  });
+}
+
+/** The navigation of the app, for anywhere, outside the screens too. */
+export const navigation: AppNavigation = {
+  switchTo,
+  push: ((name: string, config?: PushConfig) =>
+    fromCurrent('push', (id) => commands.push(id, name, config))) as AppNavigation['push'],
+  pop: () => fromCurrent('pop', (id) => commands.pop(id)),
+  popTo: (screenId) => afterStart('popTo', () => commands.popTo(screenId)),
+  popToRoot: () => fromCurrent('popToRoot', (id) => commands.popToRoot(id)),
+  replace: ((name: string, config?: PushConfig) =>
+    fromCurrent('replace', (id) => commands.replace(id, name, config))) as AppNavigation['replace'],
+  canPop: () => seenScreen((id) => commands.canPop(id)),
+  canDismiss: () => seenScreen((id) => commands.canDismiss(id)),
+  goBack: () => fromCurrent('goBack', (id) => commands.goBack(id)),
+  showColumn: (column) =>
+    fromCurrent('showColumn', (id) => commands.setColumnShown(id, column, true)),
+  hideColumn: (column) =>
+    fromCurrent('hideColumn', (id) => commands.setColumnShown(id, column, false)),
+  openMenu: (side) => fromCurrent('openMenu', (id) => openMenu(id, side)),
+  closeMenu: () => fromCurrent('closeMenu', (id) => closeMenu(id)),
+  canGoBack: () => seenScreen((id) => commands.canPop(id) || commands.canDismiss(id)),
+  setStack: ((...entries: StackEntry[]) =>
+    fromCurrent('setStack', (id) => commands.setStack(id, entries))) as AppNavigation['setStack'],
+  showInColumn: ((name: string, config?: ColumnConfig) =>
+    fromCurrent('showInColumn', (id) =>
+      commands.showInColumn(id, name, config)
+    )) as AppNavigation['showInColumn'],
+  showModal: ((name: string, config?: ModalConfig) =>
+    afterStart('showModal', () => commands.showModal(name, config))) as AppNavigation['showModal'],
+  dismissModal: (modalId) => afterStart('dismissModal', () => commands.dismissModal(modalId)),
+  dismissAllModals: () => afterStart('dismissAllModals', () => commands.dismissAllModals()),
+  showOverlay: ((name: string, config?: OverlayConfig) =>
+    afterStart('showOverlay', () =>
+      commands.showOverlay(name, config)
+    )) as AppNavigation['showOverlay'],
+  dismissOverlay: (overlayId) =>
+    afterStart('dismissOverlay', () => commands.dismissOverlay(overlayId)),
+  dismissAllOverlays: () => afterStart('dismissAllOverlays', () => commands.dismissAllOverlays()),
+  // Resolves once the state shows the tab, so the next command acts in it.
+  selectTab: (tab) =>
+    fromCurrent('selectTab', async (id) => {
+      const shown = whenTabShows(tab);
+      commands.selectTab(id, tab);
+      await shown;
+    }),
+  // A tab with an id needs no screen, only a started app.
+  setTabBadge: (badge, tab) =>
+    tab
+      ? afterStart('setTabBadge', async () => commands.setTabBadge(tab, badge, tab))
+      : fromCurrent('setTabBadge', async (id) => commands.setTabBadge(id, badge)),
+  setTheme,
+  setDirection,
+  getContext: () => getAppContext<RegisteredContext>(),
+  setContext: (next) => setAppContext<RegisteredContext>(next),
+  getState: getNavigationState,
+  getPendingLink,
+  openPendingLink,
+  clearPendingLink: () => setPendingLink(null),
+  on: onNavigationEvent,
+};