@symbiote-native/navigation 1.0.0

package/src/core/header-bar-buttons.ts

@@ -0,0 +1,212 @@
+// Header bar-button payload + dispatch: the native-shaped `headerLeftBarButtonItems`/
+// `headerRightBarButtonItems` fold react-native-screens' own ScreenStackHeaderConfig component
+// would send down, plus the buttonId/menuId -> onPress lookup that answers RNSScreenStackHeader-
+// Config's `onPressHeaderBarButtonItem`/`onPressHeaderBarButtonMenuItem` events. Self-contained:
+// only `resolveHeaderConfigView` (screen-options.ts) calls into this file, as a black box - the
+// id-tagging scheme below is this cluster's own internal invariant, never a cross-file contract.
+
+import { imageStatics } from '@symbiote-native/components';
+import { processColor } from '@symbiote-native/engine';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type {
+  IHeaderBarButtonIcon,
+  IHeaderBarButtonItem,
+  IHeaderBarButtonItemAction,
+  IHeaderBarButtonItemMenu,
+  IHeaderBarButtonMenuAction,
+  IHeaderBarButtonSubmenu,
+} from './navigator-props';
+
+// RNS flattens `icon` into sfSymbolName/xcassetName/imageSource/templateSource at native-payload
+// time (both the structured `icon` field AND the flat native keys reach native - RNS's own
+// prepareHeaderBarButtonItems keeps both), and resolves image assets through the same resolver
+// the Image component uses.
+function prepareIcon(icon: IHeaderBarButtonIcon | undefined): Record<string, unknown> {
+  if (!icon) return {};
+  switch (icon.type) {
+    case 'sfSymbol':
+      return { sfSymbolName: icon.name };
+    case 'xcasset':
+      return { xcassetName: icon.name };
+    case 'imageSource':
+      return { imageSource: imageStatics.resolveAssetSource(icon.imageSource) };
+    case 'templateSource':
+      return { templateSource: imageStatics.resolveAssetSource(icon.templateSource) };
+  }
+}
+
+type ISharedItem = IHeaderBarButtonItemAction | IHeaderBarButtonItemMenu;
+
+// The one id algorithm both the payload tagger (prepareMenuItems/prepareHeaderBarButtonItems)
+// and the dispatch-lookup builder (collectMenuHandlers/collectBarButtonHandlers) call - so a
+// change to the id scheme genuinely can't desync payload tagging from dispatch lookup.
+function buildMenuId(path: string, index: number, side: 'left' | 'right'): string {
+  return `${path}-${index}-${side}`;
+}
+
+function buildButtonId(index: number, side: 'left' | 'right'): string {
+  return `${index}-${side}`;
+}
+
+function prepareTitleStyle(
+  titleStyle: ISharedItem['titleStyle'],
+): Record<string, unknown> | undefined {
+  if (!titleStyle) return undefined;
+  return {
+    ...titleStyle,
+    color: titleStyle.color === undefined ? undefined : processColor(titleStyle.color),
+  };
+}
+
+function prepareBadge(badge: ISharedItem['badge']): Record<string, unknown> | undefined {
+  if (!badge) return undefined;
+  return {
+    ...badge,
+    style: badge.style
+      ? {
+          ...badge.style,
+          color: badge.style.color === undefined ? undefined : processColor(badge.style.color),
+          backgroundColor:
+            badge.style.backgroundColor === undefined
+              ? undefined
+              : processColor(badge.style.backgroundColor),
+        }
+      : undefined,
+  };
+}
+
+// onPress is captured separately into the buttonId/menuId -> handler map (collectMenuHandlers/
+// collectBarButtonHandlers below) and must never reach native: a function value fails Fabric's
+// dynamic-value serialization, which silently drops the WHOLE headerLeftBarButtonItems/
+// headerRightBarButtonItems array it's nested in - not just the one bad field - so bar buttons and
+// menu actions never reached native at all, despite the buttonId/menuId dispatch wiring itself
+// being entirely correct.
+function excludeOnPress<T extends { onPress: unknown }>(item: T): Omit<T, 'onPress'> {
+  const { onPress: _onPress, ...rest } = item;
+  return rest;
+}
+
+// Shared fields common to the 'button' and 'menu' item variants (title/icon/tint/badge/...) - the
+// 'spacing' variant carries none of these and passes through untouched.
+function prepareSharedFields(
+  item: IHeaderBarButtonItem & { type: 'button' | 'menu' },
+): Record<string, unknown> {
+  return {
+    ...(item.type === 'button' ? excludeOnPress(item) : item),
+    ...prepareIcon(item.icon),
+    titleStyle: prepareTitleStyle(item.titleStyle),
+    tintColor: item.tintColor === undefined ? undefined : processColor(item.tintColor),
+    badge: prepareBadge(item.badge),
+  };
+}
+
+type IMenuLike = { items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[] };
+
+// Recursively tags every menu action with a `menuId` derived from its tree position
+// (`${path}-${index}-${side}`), mirroring RNS's own prepareMenu exactly - the id must match what
+// buildHeaderBarButtonDispatch computes below, or a press silently no-ops.
+function prepareMenuItems<T extends IMenuLike>(
+  menuLike: T,
+  index: number,
+  side: 'left' | 'right',
+  path = '',
+): T {
+  return {
+    ...menuLike,
+    items: menuLike.items.map((menuItem, menuIndex) => {
+      const currentPath = path ? `${path}.${menuIndex}` : `${menuIndex}`;
+      const icon = prepareIcon(menuItem.icon);
+      if (menuItem.type === 'submenu') {
+        return { ...menuItem, ...icon, ...prepareMenuItems(menuItem, index, side, currentPath) };
+      }
+      return {
+        ...excludeOnPress(menuItem),
+        ...icon,
+        menuId: buildMenuId(currentPath, index, side),
+      };
+    }),
+  };
+}
+
+// Builds the native-shaped payload react-native-screens' own ScreenStackHeaderConfig component
+// would send down (buttonId/menuId-tagged, colors processColor'd) - this is what
+// IHeaderConfigViewProps.headerLeftBarButtonItems/headerRightBarButtonItems actually carry.
+export function prepareHeaderBarButtonItems(
+  items: IHeaderBarButtonItem[] | undefined,
+  side: 'left' | 'right',
+): unknown[] | undefined {
+  if (!items) return undefined;
+  return items.map((item, index) => {
+    if (item.type === 'spacing') return item;
+    const prepared = prepareSharedFields(item);
+    if (item.type === 'button') return { ...prepared, buttonId: buildButtonId(index, side) };
+    return { ...prepared, menu: prepareMenuItems(item.menu, index, side) };
+  });
+}
+
+function collectMenuHandlers(
+  items: (IHeaderBarButtonMenuAction | IHeaderBarButtonSubmenu)[],
+  index: number,
+  side: 'left' | 'right',
+  path: string,
+  handlers: Map<string, () => void>,
+): void {
+  items.forEach((item, menuIndex) => {
+    const currentPath = path ? `${path}.${menuIndex}` : `${menuIndex}`;
+    if (item.type === 'submenu') {
+      collectMenuHandlers(item.items, index, side, currentPath, handlers);
+      return;
+    }
+    handlers.set(buildMenuId(currentPath, index, side), item.onPress);
+  });
+}
+
+function collectBarButtonHandlers(
+  items: IHeaderBarButtonItem[] | undefined,
+  side: 'left' | 'right',
+  buttonHandlers: Map<string, () => void>,
+  menuHandlers: Map<string, () => void>,
+): void {
+  items?.forEach((item, index) => {
+    if (item.type === 'button') {
+      buttonHandlers.set(buildButtonId(index, side), item.onPress);
+    } else if (item.type === 'menu') {
+      collectMenuHandlers(item.menu.items, index, side, '', menuHandlers);
+    }
+  });
+}
+
+function readStringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+type IHeaderBarButtonDispatch = {
+  onPressHeaderBarButtonItem?: (event: ISymbioteEvent) => void;
+  onPressHeaderBarButtonMenuItem?: (event: ISymbioteEvent) => void;
+};
+
+// The buttonId/menuId → onPress lookup is built independently from prepareHeaderBarButtonItems'
+// native payload (rather than re-parsing it back out of the `unknown[]` result), over the
+// ORIGINAL typed items - but both sides call the same buildMenuId/buildButtonId, so the id
+// scheme lives in one place and can't desync payload tagging from dispatch lookup.
+export function buildHeaderBarButtonDispatch(
+  leftItems: IHeaderBarButtonItem[] | undefined,
+  rightItems: IHeaderBarButtonItem[] | undefined,
+): IHeaderBarButtonDispatch {
+  const buttonHandlers = new Map<string, () => void>();
+  const menuHandlers = new Map<string, () => void>();
+  collectBarButtonHandlers(leftItems, 'left', buttonHandlers, menuHandlers);
+  collectBarButtonHandlers(rightItems, 'right', buttonHandlers, menuHandlers);
+  if (buttonHandlers.size === 0 && menuHandlers.size === 0) return {};
+  return {
+    onPressHeaderBarButtonItem: event => {
+      const buttonId = readStringField(event.nativeEvent, 'buttonId');
+      if (buttonId !== undefined) buttonHandlers.get(buttonId)?.();
+    },
+    onPressHeaderBarButtonMenuItem: event => {
+      const menuId = readStringField(event.nativeEvent, 'menuId');
+      if (menuId !== undefined) menuHandlers.get(menuId)?.();
+    },
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,170 @@
+// @symbiote-native/navigation (core): the framework-agnostic half of the native stack navigator -
+// a pure route-stack reducer plus the react-native-screens prop folds and native-leaf prop
+// resolvers. symbiote ships zero runtime metadata for RNSScreen/RNSScreenStack/
+// RNSScreenStackHeaderConfig - the engine derives their events and color processors from
+// react-native-screens' own ViewConfig - so this layer is the pure JS every adapter reuses
+// verbatim, supplying only its lifecycle (route-key generation, useReducer/reactive state) and
+// the descriptor bridge.
+
+export * from './constants';
+
+export {
+  createInitialNavigatorState,
+  navigatorReducer,
+  computeActivityState,
+  isTopRoute,
+} from './navigator-state';
+export type { IRoute, INavigatorState, INavigatorAction } from './navigator-state';
+
+export type {
+  IStackAnimation,
+  IStackPresentation,
+  IHeaderBackButtonDisplayMode,
+  IHeaderUserInterfaceStyle,
+  IOptionalBooleanNativeProp,
+  ISheetAllowedDetents,
+  ISheetLargestUndimmedDetent,
+  ISheetInitialDetent,
+  IHeaderBarButtonIcon,
+  IHeaderBarButtonItemBadge,
+  IHeaderBarButtonItemAction,
+  IHeaderBarButtonMenuAction,
+  IHeaderBarButtonSubmenu,
+  IHeaderBarButtonItemMenu,
+  IHeaderBarButtonItemSpacing,
+  IHeaderBarButtonItem,
+  ISearchBarAutoCapitalize,
+  ISearchBarPlacement,
+  ISearchBarOptions,
+  IScreenOrientation,
+  IScreenOptions,
+  INavigatorPlatform,
+  IScreenViewProps,
+  IHeaderConfigViewProps,
+  IStackViewProps,
+  ISearchBarViewProps,
+} from './navigator-props';
+
+export { resolveHeaderConfigView, resolveScreenView, resolveSearchBarView } from './screen-options';
+
+export { buildSearchBarHandle } from './search-bar-commands';
+export type { ISearchBarCommands } from './search-bar-commands';
+
+export {
+  resolveScreenProps,
+  resolveStackProps,
+  renderHeaderConfig,
+  resolveSearchBarProps,
+  resolveScreenContentWrapperStyle,
+  resolveScreenViewName,
+  isHeaderInModal,
+  resolveHeaderInModalStackStyle,
+  resolveHeaderInModalScreenStyle,
+  buildSearchBarPassthrough,
+  resolveScreenRenderPlan,
+} from './render-stack';
+export type { IScreenRenderPlanInput, IScreenRenderPlan } from './render-stack';
+
+export { serializeNavigatorState, deserializeNavigatorState } from './state-persistence';
+
+export {
+  createNavigationEmitter,
+  diffFocusedRoute,
+  NAVIGATION_EVENT_FOCUS,
+  NAVIGATION_EVENT_BLUR,
+  NAVIGATION_EVENT_STATE,
+  NAVIGATION_EVENT_BEFORE_REMOVE,
+} from './navigation-events';
+export type {
+  INavigationEmitter,
+  INavigationEventListener,
+  INavigationEventName,
+  IFocusTransition,
+} from './navigation-events';
+
+// Runtime guards shared across core (and re-exported for adapters narrowing their own untyped
+// inputs - vnode props, gesture/event data, persisted JSON) - see guards.ts's header for which
+// call sites this consolidates and why array-exclusion is the right default everywhere it's used.
+export { isRecord } from './guards';
+
+// Bottom-tabs navigator: a FOCUSED-INDEX router (not a stack - see tab-router-state.ts) driving
+// a pure-JS tab bar render, framework-agnostic and shared verbatim by every adapter.
+export { createInitialTabState, tabRouterReducer, isFocusedRoute } from './tab-router-state';
+export type { ITabRouterState, ITabRouterAction } from './tab-router-state';
+
+export type { ITabBarIcon, ITabOptions } from './tab-options';
+
+export { renderTabBarItem, renderTabBar } from './render-tabs';
+export type { ITabBarItemView, ITabBarViewProps } from './render-tabs';
+
+// Linking config: resolves a URL to a route (and back), the piece @react-navigation's
+// NavigationContainer `linking` prop provides on top of the framework-agnostic Linking module.
+export { resolveRouteFromUrl, resolveUrlFromRoute } from './linking-config';
+export type { ILinkingConfig, IScreenLinkingConfig } from './linking-config';
+
+// Drawer navigator: an OPEN/CLOSED-flag router over a fixed route list (see
+// drawer-router-state.ts's header for why it isn't a push/pop stack), a pure swipe/geometry math
+// module, and a Descriptor render fn - all framework-agnostic, shared verbatim by every adapter.
+export {
+  createInitialDrawerRouterState,
+  drawerRouterReducer,
+  focusedDrawerRoute,
+} from './drawer-router-state';
+export type { IDrawerRouterState, IDrawerRouterAction } from './drawer-router-state';
+
+export type {
+  IDrawerType,
+  IDrawerPosition,
+  IDrawerOptions,
+  IDrawerScreenOptions,
+  IDrawerGeometry,
+  ISwipeIntent,
+} from './drawer-options';
+export {
+  DRAWER_DEFAULT_TYPE,
+  DRAWER_DEFAULT_POSITION,
+  DRAWER_DEFAULT_WIDTH,
+  DRAWER_DEFAULT_OVERLAY_COLOR,
+  DRAWER_DEFAULT_SWIPE_ENABLED,
+  DRAWER_DEFAULT_SWIPE_EDGE_WIDTH,
+  DRAWER_DEFAULT_SWIPE_MIN_DISTANCE,
+  DRAWER_DEFAULT_SWIPE_MIN_VELOCITY,
+  resolveDrawerType,
+  resolveDrawerPosition,
+  resolveDrawerWidth,
+  isDrawerAnimated,
+  isDrawerOverlayVisible,
+  resolveDrawerGeometry,
+  isSwipeStartInEdge,
+  isHorizontalDrag,
+  resolveSwipeIntent,
+  clamp01,
+  startPageXOf,
+  resolveDragProgress,
+  shouldClaimDrawerSwipe,
+  resolveDrawerSlotInterpolation,
+} from './drawer-options';
+export type {
+  IDrawerInterpolationRange,
+  IDrawerContentSlotInterpolation,
+  IDrawerOverlaySlotInterpolation,
+  IDrawerPanelSlotInterpolation,
+} from './drawer-options';
+
+export { renderDrawer, drawerChildOrder } from './render-drawer';
+export type { IDrawerSlot, IDrawerViewProps } from './render-drawer';
+
+// Imperative navigator handles (Stack/Tab/Drawer): framework-agnostic, declared once here and
+// re-exported verbatim by every adapter (see navigator-handles.ts's header).
+export type {
+  INavigatorHandle,
+  ITabNavigatorHandle,
+  IDrawerNavigatorHandle,
+  IDrawerDescriptorMap,
+  IAnyNavigatorHandle,
+} from './navigator-handles';
+export {
+  isStackNavigatorHandle,
+  isTabNavigatorHandle,
+  isDrawerNavigatorHandle,
+} from './navigator-handles';

package/src/core/linking-config/index.ts

@@ -0,0 +1,209 @@
+// Linking config: the piece @react-navigation's `NavigationContainer`'s `linking` prop provides
+// on top of the framework-agnostic `Linking` module (core/engine/src/linking) - resolving a URL
+// ('myapp://user/42', '/user/42') to a route, and a route back to a URL. This is OUR OWN type,
+// not imported from react-navigation, kept close to its shape (`prefixes` + `config.screens`)
+// only so the DX is familiar.
+//
+// Why hand-rolled matching instead of react-router's `matchPath`/`generatePath` (evaluated per
+// task): react-router 8's package has no subpath export for the pure `lib/router/utils.ts`
+// matcher - its only general entry point (`.`) eagerly imports `./lib/dom/*`
+// (BrowserRouter/ScrollRestoration/cookies) and `./lib/server-runtime/*`, code that assumes DOM
+// and Node globals a Metro/Hermes RN bundle doesn't have; its `peerDependencies` also pin
+// `react-dom`, which this DOM-free monorepo never installs (see CLAUDE.md
+// react_native_is_an_explicit_top_level_peer - no foreign runtime singleton gets smuggled in).
+// On top of the bundling risk, `matchPath`'s/`generatePath`'s param-name extraction is a
+// template-literal-type trick that only fires for a compile-time LITERAL path string; our
+// patterns come from a runtime config object (`Path` widens to plain `string`), so the generic
+// degrades to an empty params type and using the result would force an `as` cast - forbidden by
+// this project's TS conventions. A minimal `:param`-segment matcher sidesteps both problems and
+// is the right size for a single flat Stack (no optional/splat segments - no nested-navigator use
+// for them yet).
+
+import { dlog } from '@symbiote-native/engine';
+import type { IRoute } from '../navigator-state';
+import { isRecord } from '../guards';
+
+export type IScreenLinkingConfig =
+  | string
+  | {
+      path?: string;
+      screens?: Record<string, IScreenLinkingConfig>;
+    };
+
+export type ILinkingConfig = {
+  prefixes: string[];
+  config: {
+    screens: Record<string, IScreenLinkingConfig>;
+  };
+};
+
+type IFlatRoutePattern = {
+  name: string;
+  pattern: string;
+};
+
+// Strips leading/trailing slashes so segments join predictably regardless of how the caller
+// wrote a path ('feed/:sort', '/feed/:sort/', etc).
+function normalizeSegment(segment: string): string {
+  return segment.replace(/^\/+|\/+$/g, '');
+}
+
+function joinPath(parent: string, child: string): string {
+  const parts = [normalizeSegment(parent), normalizeSegment(child)].filter(part => part.length > 0);
+  return parts.join('/');
+}
+
+// Walks `screens` recursively, accumulating the path down to each LEAF screen. Unlike
+// react-navigation (which resolves nested config into nested navigation state), our navigator is
+// a single flat Stack - a `screens` group with no `path` of its own is transparent (consumes no
+// URL segment); a group WITH a `path` but no nested `screens` is itself a leaf using that path.
+function flattenScreens(
+  screens: Record<string, IScreenLinkingConfig>,
+  parentPath: string,
+  out: IFlatRoutePattern[],
+): IFlatRoutePattern[] {
+  for (const [name, entry] of Object.entries(screens)) {
+    if (typeof entry === 'string') {
+      out.push({ name, pattern: joinPath(parentPath, entry) });
+      continue;
+    }
+
+    const nextParent = entry.path !== undefined ? joinPath(parentPath, entry.path) : parentPath;
+
+    if (entry.screens !== undefined) {
+      flattenScreens(entry.screens, nextParent, out);
+    } else if (entry.path !== undefined) {
+      out.push({ name, pattern: nextParent });
+    } else {
+      dlog(`linking-config: screen "${name}" has neither a path nor nested screens, skipping`);
+    }
+  }
+  return out;
+}
+
+function dynamicSegmentCount(pattern: string): number {
+  if (pattern.length === 0) return 0;
+  return pattern.split('/').filter(segment => segment.startsWith(':')).length;
+}
+
+function segmentCount(pattern: string): number {
+  return pattern.length === 0 ? 0 : pattern.split('/').length;
+}
+
+// More static segments should win over a param that would also match (e.g. a literal
+// '/user/me' pattern over '/user/:id'), mirroring how react-navigation prefers exact matches.
+function bySpecificity(a: IFlatRoutePattern, b: IFlatRoutePattern): number {
+  const dynamicDiff = dynamicSegmentCount(a.pattern) - dynamicSegmentCount(b.pattern);
+  if (dynamicDiff !== 0) return dynamicDiff;
+  return segmentCount(b.pattern) - segmentCount(a.pattern);
+}
+
+function matchPattern(pattern: string, pathname: string): Record<string, string> | null {
+  const patternSegments = pattern.length === 0 ? [] : pattern.split('/');
+  const pathSegments = pathname.length === 0 ? [] : pathname.split('/');
+  if (patternSegments.length !== pathSegments.length) return null;
+
+  const params: Record<string, string> = {};
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const patternSegment = patternSegments[index];
+    const pathSegment = pathSegments[index];
+    if (patternSegment.startsWith(':')) {
+      params[patternSegment.slice(1)] = decodeURIComponent(pathSegment);
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return params;
+}
+
+function stripQueryAndHash(url: string): string {
+  const match = /[?#]/.exec(url);
+  return match === null ? url : url.slice(0, match.index);
+}
+
+// Resolves a full URL down to the bare path segment string ('user/42', no leading slash) by
+// stripping the longest matching configured prefix, falling back to treating the URL as an
+// already-bare path when it starts with '/' (the task's second example form). Returns null when
+// neither applies - an unrecognized scheme/host, not "no route matched".
+function extractPathname(config: ILinkingConfig, url: string): string | null {
+  const withoutQuery = stripQueryAndHash(url);
+  const sortedPrefixes = [...config.prefixes].sort((a, b) => b.length - a.length);
+  for (const prefix of sortedPrefixes) {
+    if (withoutQuery.startsWith(prefix)) {
+      return normalizeSegment(withoutQuery.slice(prefix.length));
+    }
+  }
+  if (withoutQuery.startsWith('/')) return normalizeSegment(withoutQuery);
+  return null;
+}
+
+export function resolveRouteFromUrl(config: ILinkingConfig, url: string): IRoute<unknown> | null {
+  const pathname = extractPathname(config, url);
+  if (pathname === null) {
+    dlog(`linking-config: url "${url}" matched no configured prefix`);
+    return null;
+  }
+
+  const candidates = flattenScreens(config.config.screens, '', []).sort(bySpecificity);
+  for (const candidate of candidates) {
+    const params = matchPattern(candidate.pattern, pathname);
+    if (params !== null) {
+      dlog(`linking-config: resolved "${url}" -> ${candidate.name}`);
+      // `key` is not real route identity here - the navigator mints its own on push/replace
+      // (stack.ts's createRoute); `name` is a stable enough placeholder to satisfy IRoute's shape.
+      return {
+        key: candidate.name,
+        name: candidate.name,
+        params: Object.keys(params).length > 0 ? params : undefined,
+      };
+    }
+  }
+
+  dlog(`linking-config: url "${url}" (path "${pathname}") matched no configured screen`);
+  return null;
+}
+
+// The inverse of matchPattern: fills a pattern's ':param' segments from `params`, or returns
+// null when a required param is missing (mirrors react-router's generatePath throwing, minus the
+// throw - a resolver returning null reads more naturally at the call site here).
+function fillPattern(pattern: string, params: unknown): string | null {
+  if (pattern.length === 0) return '';
+  const source = isRecord(params) ? params : {};
+  const segments: string[] = [];
+  for (const segment of pattern.split('/')) {
+    if (!segment.startsWith(':')) {
+      segments.push(segment);
+      continue;
+    }
+    const value = source[segment.slice(1)];
+    if (value === undefined || value === null) return null;
+    segments.push(encodeURIComponent(String(value)));
+  }
+  return segments.join('/');
+}
+
+export function resolveUrlFromRoute(config: ILinkingConfig, route: IRoute<unknown>): string | null {
+  const candidate = flattenScreens(config.config.screens, '', []).find(
+    entry => entry.name === route.name,
+  );
+  if (candidate === undefined) {
+    dlog(`linking-config: no configured screen for route name "${route.name}"`);
+    return null;
+  }
+
+  const path = fillPattern(candidate.pattern, route.params);
+  if (path === null) {
+    dlog(
+      `linking-config: route "${route.name}" is missing a param required by "${candidate.pattern}"`,
+    );
+    return null;
+  }
+
+  const prefix = config.prefixes[0];
+  if (prefix === undefined) return path.length > 0 ? `/${path}` : '/';
+
+  // A prefix already carrying its own trailing separator ('myapp://') must not be truncated to
+  // 'myapp:/' by naively slicing one char off - only add a '/' when the prefix doesn't have one.
+  if (path.length === 0) return prefix;
+  return prefix.endsWith('/') ? `${prefix}${path}` : `${prefix}/${path}`;
+}