@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.10

package/src/engine/layout.ts

@@ -14,6 +14,7 @@ import { nextId } from './ids';
 import { showNativeScreen } from './nativeScreens';
 import { toNativeOptions } from './options';
 import { setProps } from './props';
+import { noteOwnOptions } from './rememberedOptions';
 import { getStartInfo } from './native';
 import { noteAlone } from './places';
 import {
@@ -103,6 +104,13 @@ function screen(component: LayoutComponent, inPair = false, keyed = !inPair): La
   if (nativeName) {
     // A native screen: its props go to the native side as data, its own options over those of the show.
     const options = takeButtonHandlers(id, component.options ?? {});
+    if (__DEV__) {
+      noteOwnOptions(
+        id,
+        name,
+        mergeOptions(screenOptions(name, props ?? {}), component.options ?? {})
+      );
+    }
     const node = external({
       id,
       name: nativeName,
@@ -113,8 +121,9 @@ function screen(component: LayoutComponent, inPair = false, keyed = !inPair): La
   }
   // The screen's own options under those of the show (a command has them there already: merging again changes
   // nothing).
-  const own = screenOptions(name, props ?? {});
-  const options = takeButtonHandlers(id, mergeOptions(own, component.options ?? {}));
+  const own = mergeOptions(screenOptions(name, props ?? {}), component.options ?? {});
+  noteOwnOptions(id, name, own);
+  const options = takeButtonHandlers(id, own);
   const key = keyed ? screenKey(name, props ?? {}) : undefined;
   setProps(id, props);
   return {
@@ -122,7 +131,7 @@ function screen(component: LayoutComponent, inPair = false, keyed = !inPair): La
     type: 'Component',
     data: {
       name: rendersInSlot(name) ? slotName(id, name) : name,
-      options: toNativeOptions(options),
+      options: toNativeOptions(options, id),
       ...(key !== undefined && { key }),
     },
     children: [],
@@ -167,12 +176,13 @@ function arrangement(
 }
 
 function external(component: ExternalComponent): LayoutNode {
+  const id = component.id || nextId('ExternalComponent');
   return {
-    id: component.id || nextId('ExternalComponent'),
+    id,
     type: 'ExternalComponent',
     data: {
       name: String(component.name),
-      options: toNativeOptions(component.options),
+      options: toNativeOptions(component.options, id),
       passProps: component.passProps,
     },
     children: [],
@@ -185,10 +195,11 @@ function parent(
   options: Options | undefined,
   children: Layout[] = []
 ): LayoutNode {
+  const nodeId = id || nextId(type);
   return {
-    id: id || nextId(type),
+    id: nodeId,
     type,
-    data: { options: toNativeOptions(options) },
+    data: { options: toNativeOptions(options, nodeId) },
     children: children.map(toNativeLayout),
   };
 }
@@ -213,10 +224,11 @@ function sideMenu(menu: LayoutSideMenu): LayoutNode {
     data: {},
     children: [toNativeLayout(content)],
   });
+  const id = menu.id || nextId('SideMenuRoot');
   return {
-    id: menu.id || nextId('SideMenuRoot'),
+    id,
     type: 'SideMenuRoot',
-    data: { options: toNativeOptions(menu.options) },
+    data: { options: toNativeOptions(menu.options, id) },
     children: [
       ...(menu.left ? [side('SideMenuLeft', menu.left)] : []),
       side('SideMenuCenter', menu.center),
@@ -238,10 +250,14 @@ function splitView(split: LayoutSplitView): LayoutNode {
     ] as [string, Layout | undefined][]
   ).filter((column): column is [string, Layout] => column[1] !== undefined);
   const present = split.master && split.detail ? columns : [];
+  const id = split.id || nextId('SplitView');
   return {
-    id: split.id || nextId('SplitView'),
+    id,
     type: 'SplitView',
-    data: { options: toNativeOptions(split.options), columns: present.map(([column]) => column) },
+    data: {
+      options: toNativeOptions(split.options, id),
+      columns: present.map(([column]) => column),
+    },
     children: present.map(([, content]) => toNativeLayout(content)),
   };
 }

package/src/engine/nativeScreens.ts

@@ -38,6 +38,8 @@ interface NativeProps {
 interface OpenScreen {
   id: string;
   name: string;
+  /** The props the command gave, as they are. */
+  given: object;
   props: NativeProps;
   /** The data the native side has, and the names of the functions; none before the command sends the screen. */
   sent?: { data: Map<string, string>; functions: string };
@@ -78,7 +80,7 @@ export const nativeScreenHooks = {
  * screen with `useProps` starts its hook, and its props go in once the hook has returned (`whenNativeScreensReady`).
  */
 export function showNativeScreen(node: LayoutNode, name: string, props: object): void {
-  const screen: OpenScreen = { id: node.id, name, props: toNativeProps(props) };
+  const screen: OpenScreen = { id: node.id, name, given: props, props: toNativeProps(props) };
   const Controller = nativeScreenController(name);
   if (Controller) {
     screen.first = deferred();
@@ -135,6 +137,13 @@ export function callNativeScreenFunction(id: string, name: string, args: unknown
   return fn(...args);
 }
 
+/** The native screens with the name that are open, each with the props its command gave. */
+export function openNativeScreens(name: string): { id: string; props: object }[] {
+  return [...screens.values()]
+    .filter((screen) => screen.name === name)
+    .map((screen) => ({ id: screen.id, props: screen.given }));
+}
+
 /** The native screen with the id, for the navigation of its calls. */
 export function nativeScreenInfo(id: string): { id: string; name: string } | undefined {
   const screen = screens.get(id);

package/src/engine/options.ts

@@ -1,17 +1,27 @@
-import { DynamicColorIOS, Image, Platform, processColor } from 'react-native';
+import { Image, Platform, processColor } from 'react-native';
 import type { ColorValue, ImageSourcePropType } from 'react-native';
 import { nextId } from './ids';
-import { rememberButtonRoot, setProps } from './props';
+import { rememberButtonRoot, rememberOptionsComponent, setProps } from './props';
 
 type Fields = Record<string, unknown>;
 
 /**
  * The options as the native side reads them: colors in the format of the platform, images resolved, and every
  * component in them with an id of its own (its props stay in JavaScript). Options come in their own form only:
- * animations with `enter` and `exit`, `searchBar` and `interpolation` as objects.
+ * animations with `enter` and `exit`, `searchBar` and `interpolation` as objects. `owner` is the id of the node the
+ * options are for, or `'defaultOptions'`: a component without an id of its own gets one made of the owner, its place
+ * in the options and its name, the same for every `mergeOptions` of the node, so the native side keeps the mounted
+ * component and only its props change. Without an owner each conversion gives it a new one.
  */
-export function toNativeOptions<T>(options: T): T {
-  return convert(options) as T;
+export function toNativeOptions<T>(options: T, owner?: string): T {
+  return convert(options, undefined, { owner, path: '' }) as T;
+}
+
+// Where a value is in the options being converted: the node they are for, and the path to the value
+// (`topBar.rightButtons[0].component`).
+interface Place {
+  owner: string | undefined;
+  path: string;
 }
 
 /**
@@ -35,11 +45,16 @@ function isGroup(value: unknown): value is Fields {
   return isFields(value) && !Array.isArray(value);
 }
 
-function convert(value: unknown, key?: string): unknown {
+function convert(value: unknown, key: string | undefined, place: Place): unknown {
   if (key !== undefined && isColor(key)) return nativeColor(value);
   if (key !== undefined && isImage(key)) return nativeImage(value);
   if (Array.isArray(value)) {
-    const items = value.map((item) => convert(item));
+    // An item is known by its id where it has one (a button, a suggestion), so a component keeps its root when the
+    // list around it changes; by its place in the list otherwise.
+    const items = value.map((item, index) => {
+      const id = isFields(item) && typeof item.id === 'string' && item.id ? item.id : index;
+      return convert(item, undefined, { ...place, path: `${place.path}[${id}]` });
+    });
     if (key?.endsWith('Buttons') || key === 'buttons') items.forEach(noteButtonRoot);
     return key?.endsWith('Buttons') ? items.map(takeButtonProps) : items;
   }
@@ -47,9 +62,12 @@ function convert(value: unknown, key?: string): unknown {
   const result: Fields = {};
   for (const [name, item] of Object.entries(withSymbols(value))) {
     // The props of a component are its own, not options.
-    result[name] = name === 'passProps' ? item : convert(item, name);
+    const path = place.path ? `${place.path}.${name}` : name;
+    result[name] = name === 'passProps' ? item : convert(item, name, { ...place, path });
   }
-  return key === 'component' || key === 'resultsComponent' ? takeComponentProps(result) : result;
+  return key === 'component' || key === 'resultsComponent'
+    ? takeComponentProps(result, place)
+    : result;
 }
 
 function isColor(key: string): boolean {
@@ -105,13 +123,23 @@ function isFields(value: unknown): value is Fields {
   return typeof value === 'object' && value !== null;
 }
 
-// A component in the options gets an id; the native side creates it with that id, and its props wait here.
-function takeComponentProps({ passProps, ...component }: Fields): Fields {
-  const componentId = (component.id as string | undefined) || nextId('CustomComponent');
+// A component in the options gets an id; the native side creates it with that id, and its props wait here. Without
+// an id of its own it is the owner's, the place of the component (`topBar.title`, `topBar.rightButtons[Save]` by the
+// button's id, `topBar.searchBar.resultsComponent`) and its name: another name there is another component.
+function takeComponentProps({ passProps, ...component }: Fields, place: Place): Fields {
+  const componentId = (component.id as string | undefined) || componentIdAt(place, component.name);
   if (passProps) setProps(componentId, passProps as object);
   return { ...component, componentId };
 }
 
+function componentIdAt({ owner, path }: Place, name: unknown): string {
+  if (owner === undefined) return nextId('CustomComponent');
+  const at = path.endsWith('.component') ? path.slice(0, -'.component'.length) : path;
+  const id = `${owner}/${at}/${String(name)}`;
+  rememberOptionsComponent(owner, id);
+  return id;
+}
+
 // The component of a bar button (the top bar's `*Buttons`, the toolbar's `buttons`) is a root the native side only
 // sizes: its wrapper centers the content in the button's slot.
 function noteButtonRoot(button: unknown): void {
@@ -134,19 +162,17 @@ function nativeColor(value: unknown): unknown {
   return Platform.OS === 'ios' ? iosColor(value) : androidColor(value);
 }
 
-// One color, a pair for the light and the dark appearance, or a semantic color; null takes the color away.
+// One color, a pair for the light and the dark appearance, or a semantic color; null takes the color away. A pair goes
+// as `{ light, dark }`, an app's `DynamicColorIOS` too; a side without a color is left out and shows the platform's.
 function iosColor(value: unknown): unknown {
   if (value === null) return 'NoColor';
   if (!isFields(value)) return processColor(value as ColorValue);
   if ('semantic' in value) return value;
   const pair = ('dynamic' in value ? value.dynamic : value) as {
-    light: ColorValue;
-    dark: ColorValue;
+    light?: ColorValue;
+    dark?: ColorValue;
   };
-  return DynamicColorIOS({
-    light: processColor(pair.light) as ColorValue,
-    dark: processColor(pair.dark) as ColorValue,
-  });
+  return { light: processColor(pair.light), dark: processColor(pair.dark) };
 }
 
 // Android always takes a pair; one color goes to both, and the side without a color has none.

package/src/engine/optionsChange.ts

@@ -0,0 +1,107 @@
+import type { Options } from '../interfaces/Options';
+
+/** What an edit of a screen's options changed: the options to merge, and the paths of the options it took out. */
+export interface OptionsChange {
+  /** The options that are new or have another value; undefined when none. */
+  merge?: Options;
+  /** The paths of the options set before and not now, such as `['topBar', 'subtitle']`. */
+  removed: string[][];
+}
+
+/**
+ * What `next` changes of `previous`, both the options of one screen. Objects compare key by key; anything else, an
+ * array such as buttons too, changes as a whole, and a function by identity (`sameValue`).
+ */
+export function optionsChange(previous: Options, next: Options): OptionsChange {
+  const removed: string[][] = [];
+  const merge = changed(previous, next, [], removed) as Options | undefined;
+  return merge ? { merge, removed } : { removed };
+}
+
+function changed(previous: unknown, next: unknown, path: string[], removed: string[][]): unknown {
+  if (isWholeValue(path) && isPlainObject(previous) && isPlainObject(next)) {
+    if (sameValue(previous, next)) return undefined;
+    // A part of it taken out: the native side may merge the parts, so the value goes first.
+    if (Object.keys(previous).some((key) => next[key] === undefined)) removed.push(path);
+    return next;
+  }
+  if (!isPlainObject(previous) || !isPlainObject(next)) {
+    return sameValue(previous, next) ? undefined : next;
+  }
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(next)) {
+    if (value === undefined) continue;
+    const change = changed(previous[key], value, [...path, key], removed);
+    if (change !== undefined) result[key] = change;
+  }
+  for (const [key, value] of Object.entries(previous)) {
+    if (value !== undefined && next[key] === undefined) removed.push([...path, key]);
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+// A color (`{ light, dark }`), an icon or an image, and a menu are one value each on the native side, not a group: a
+// part of one taken out goes as the whole value again.
+function isWholeValue(path: string[]): boolean {
+  const key = path[path.length - 1];
+  return key !== undefined && /^(color|icon|image|menu)$|(Color|Icon|Image)$/.test(key);
+}
+
+/**
+ * Whether two values are the same: plain objects key by key, arrays item by item, anything else, functions too, by
+ * identity. A module that ran again makes its functions anew, so they count as changed: Hermes keeps no source to tell
+ * an edited one, and sending a button's handler again costs little. With `functionsAlike` any two functions are alike.
+ */
+export function sameValue(a: unknown, b: unknown, functionsAlike = false): boolean {
+  if (functionsAlike && typeof a === 'function' && typeof b === 'function') return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return (
+      a.length === b.length && a.every((item, index) => sameValue(item, b[index], functionsAlike))
+    );
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((key) => sameValue(a[key], b[key], functionsAlike));
+  }
+  return Object.is(a, b);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * The part of an edit's change that the screen shows the old definition's value of: where the command that showed it,
+ * or a merge since, set another value, that value stays. `before` is what the old definition gave, `own` the screen's
+ * own options now.
+ */
+export function changeOverOwn(change: OptionsChange, before: Options, own: Options): OptionsChange {
+  // The functions of the definition are made anew each time it is read (a chain's button handlers): any function
+  // there stands for the definition's.
+  const fromDefinition = (path: string[]) =>
+    sameValue(valueAt(own, path), valueAt(before, path), true);
+  const removed = change.removed.filter(fromDefinition);
+  const merge =
+    change.merge && (keptWhere(change.merge, [], fromDefinition) as Options | undefined);
+  return merge ? { merge, removed } : { removed };
+}
+
+function keptWhere(value: unknown, path: string[], keep: (path: string[]) => boolean): unknown {
+  if (!isPlainObject(value) || isWholeValue(path)) return keep(path) ? value : undefined;
+  const result: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    const kept = keptWhere(item, [...path, key], keep);
+    if (kept !== undefined) result[key] = kept;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/** The value at a path of options, such as `['topBar', 'title', 'text']`; undefined where there is none. */
+export function valueAt(options: unknown, path: readonly string[]): unknown {
+  return path.reduce<unknown>(
+    (value, key) => (isPlainObject(value) ? value[key] : undefined),
+    options
+  );
+}

package/src/engine/places.ts

@@ -1,6 +1,7 @@
 import type { SplitViewColumnsStackedEvent } from '../interfaces/Events';
 import type { LayoutNode } from './layout';
 import { onNativeEvent } from './native';
+import { forgetProps } from './props';
 import { screenNameOf } from './slots';
 
 // Where each screen is, noted as the engine builds the layouts of the commands: what it shows in and its place in its
@@ -51,6 +52,11 @@ const stackedSplits = new Set<string>();
 let listeningToSplitViews = false;
 // The primaries of pairs shown alone, noted as their node is built, until their place is noted.
 const alone = new Set<string>();
+// The layouts each screen shows in (its stack, pair, tabs, menu, split view, and the root of its layer), and how many
+// live screens each layout holds. A layout whose last screen went is gone, and with it the props of the components the
+// library named in its options: they stay as long as any of its screens may show them again.
+const layoutsOfScreen = new Map<string, readonly string[]>();
+const screensInLayout = new Map<string, number>();
 // The last screens that went, so a command from one of them can say so; a screen the engine never saw is not one.
 const gone = new Set<string>();
 const GONE_KEPT = 200;
@@ -59,6 +65,15 @@ export function placeOf(screenId: string): ScreenPlace | undefined {
   return places.get(screenId);
 }
 
+/** The first screen of a stack, as the engine noted it; with a pair first, its primary. */
+export function firstScreenOf(stack: string): string | undefined {
+  for (const [id, place] of places) {
+    if (place.stack === stack && place.index === 0 && place.arrangement?.placement !== 'secondary')
+      return id;
+  }
+  return undefined;
+}
+
 /** Notes that a screen is the primary of a pair shown alone, where the native side shows no pairs. */
 export function noteAlone(screenId: string): void {
   alone.add(screenId);
@@ -69,9 +84,15 @@ export function isGone(screenId: string): boolean {
   return gone.has(screenId);
 }
 
+/** The layouts the screen shows in, outermost first: those whose screens come with it in a command go in it too. */
+export function layoutsOf(screenId: string): readonly string[] {
+  return layoutsOfScreen.get(screenId) ?? [];
+}
+
 /**
  * Notes the screens of a layout, the first of a stack at `index`. A modal or an overlay given as a whole is a layer of
- * its own; screens added to one, such as a push, take the layer of the screen they come from.
+ * its own; screens added to one, such as a push, take the layer of the screen they come from, and `within`, the
+ * layouts they show in (`layoutsOf` that screen).
  */
 export function notePlaces(
   node: LayoutNode,
@@ -79,12 +100,14 @@ export function notePlaces(
   stack: string | null = null,
   index = 0,
   menu?: ScreenPlace['menu'],
-  layer: string = container === 'root' ? 'root' : node.id
+  layer: string = container === 'root' ? 'root' : node.id,
+  within: readonly string[] = []
 ): void {
   if (node.type === 'Component' || node.type === 'ExternalComponent') {
     const name = node.data.name ?? '';
     gone.delete(node.id);
     columnOfScreen.delete(node.id);
+    noteLayouts(node.id, within);
     places.set(node.id, {
       name: screenNameOf(name),
       container,
@@ -99,7 +122,7 @@ export function notePlaces(
   } else if (node.type === 'Arrangement') {
     // One entry of its stack: both screens have its place there, and each knows the pair.
     node.children.forEach((child, childIndex) => {
-      notePlaces(child, container, stack, index, menu, layer);
+      notePlaces(child, container, stack, index, menu, layer, [...within, node.id]);
       const place = places.get(child.id);
       if (place) {
         const placement = childIndex === 0 ? 'primary' : 'secondary';
@@ -109,7 +132,7 @@ export function notePlaces(
   } else if (node.type === 'Stack') {
     columnOfStack.delete(node.id);
     node.children.forEach((child, childIndex) =>
-      notePlaces(child, container, node.id, childIndex, menu, layer)
+      notePlaces(child, container, node.id, childIndex, menu, layer, [...within, node.id])
     );
   } else if (node.type === 'SplitView') {
     // A split view sent again with its id starts anew: its columns are noted again, and it isn't one stack until the
@@ -118,7 +141,7 @@ export function notePlaces(
     const columns = node.data.columns ?? [];
     const stacks: Partial<Record<string, string>> = {};
     node.children.forEach((child, childIndex) => {
-      notePlaces(child, container, null, 0, menu, layer);
+      notePlaces(child, container, null, 0, menu, layer, [...within, node.id]);
       const column = columns[childIndex];
       if (!column) return;
       if (child.type === 'Stack') stacks[column] = child.id;
@@ -128,12 +151,46 @@ export function notePlaces(
   } else if (node.type === 'SideMenuRoot') {
     for (const part of node.children) {
       const side = MENU_PARTS[part.type];
+      const parts = [...within, node.id, part.id];
       part.children.forEach((child) =>
-        notePlaces(child, container, null, 0, side ? { id: node.id, part: side } : menu, layer)
+        notePlaces(
+          child,
+          container,
+          null,
+          0,
+          side ? { id: node.id, part: side } : menu,
+          layer,
+          parts
+        )
       );
     }
   } else {
-    node.children.forEach((child) => notePlaces(child, container, null, 0, menu, layer));
+    node.children.forEach((child) =>
+      notePlaces(child, container, null, 0, menu, layer, [...within, node.id])
+    );
+  }
+}
+
+// A screen noted again under its id (a layout sent again) leaves the layouts it was in before.
+function noteLayouts(screenId: string, within: readonly string[]): void {
+  leaveLayouts(screenId);
+  const layouts = [...new Set(within)];
+  layoutsOfScreen.set(screenId, layouts);
+  for (const layout of layouts) screensInLayout.set(layout, (screensInLayout.get(layout) ?? 0) + 1);
+}
+
+function leaveLayouts(screenId: string): void {
+  const layouts = layoutsOfScreen.get(screenId);
+  if (!layouts) return;
+  layoutsOfScreen.delete(screenId);
+  for (const layout of layouts) {
+    const count = (screensInLayout.get(layout) ?? 1) - 1;
+    if (count > 0) {
+      screensInLayout.set(layout, count);
+      continue;
+    }
+    screensInLayout.delete(layout);
+    forgetProps(layout);
   }
 }
 
@@ -198,6 +255,7 @@ export function listenToSplitViews(): void {
 
 /** The screen is gone. */
 export function forgetPlace(screenId: string): void {
+  leaveLayouts(screenId);
   places.delete(screenId);
   columnOfScreen.delete(screenId);
   gone.add(screenId);

package/src/engine/props.ts

@@ -7,6 +7,11 @@ const watchers = new Map<string, Set<() => void>>();
 const none = {};
 // The roots that are the components of bar buttons: their wrapper centers the content in the button's slot.
 const buttonRoots = new Set<string>();
+// The ids the library gave components in options, by the node whose options they are in. Such an id stays the same
+// for every show of the node and may have several roots at once (a component of the default or a stack's options):
+// its props go with the node, not with a root.
+const optionComponents = new Map<string, Set<string>>();
+const optionComponentIds = new Set<string>();
 
 export function setProps(id: string, props: object | undefined): void {
   if (props === undefined) byId.delete(id);
@@ -38,8 +43,32 @@ export function isButtonRoot(id: string): boolean {
   return buttonRoots.has(id);
 }
 
-/** The view is gone: its props, and whether it is a button's root, are not needed again. */
+/** Notes an id the library gave a component in the options of the node `owner`. */
+export function rememberOptionsComponent(owner: string, id: string): void {
+  let ids = optionComponents.get(owner);
+  if (!ids) optionComponents.set(owner, (ids = new Set()));
+  ids.add(id);
+  optionComponentIds.add(id);
+}
+
+/** Whether the library gave the id to a component in options: its props go with the node, not with a root. */
+export function isOptionsComponent(id: string): boolean {
+  return optionComponentIds.has(id);
+}
+
+/**
+ * The view is gone: its props, and whether it is a button's root, are not needed again; nor are those of the
+ * components the library named in its options.
+ */
 export function forgetProps(id: string): void {
   byId.delete(id);
   buttonRoots.delete(id);
+  const ids = optionComponents.get(id);
+  if (!ids) return;
+  optionComponents.delete(id);
+  for (const component of ids) {
+    byId.delete(component);
+    buttonRoots.delete(component);
+    optionComponentIds.delete(component);
+  }
 }

package/src/engine/refresh.ts

@@ -0,0 +1,97 @@
+// Fast Refresh runs an edited module again, and every component it exports is a new function. React Refresh keeps
+// the versions of one component in a family: Metro registers each export under its module and name, and React renders
+// the newest version of the family in place of the old one. What the library keeps of a screen (its options, its key,
+// its pair) is read through the same family, so an edit reaches it without a reload.
+
+/** The versions of one component React Refresh keeps, `current` the newest. */
+interface Family {
+  current: unknown;
+}
+
+interface ReactRefresh {
+  getFamilyByType?: (type: unknown) => Family | undefined;
+  register?: (type: unknown, id: string) => void;
+  createSignatureFunctionForTransform?: () => (
+    type: unknown,
+    key: string,
+    forceReset?: boolean
+  ) => unknown;
+}
+
+// React Native puts React Refresh where Metro's module system finds it, in development only.
+function reactRefresh(): ReactRefresh | undefined {
+  if (!__DEV__) return undefined;
+  const global = globalThis as { __METRO_GLOBAL_PREFIX__?: string } & Record<string, unknown>;
+  return global[`${global.__METRO_GLOBAL_PREFIX__ ?? ''}__ReactRefresh`] as
+    ReactRefresh | undefined;
+}
+
+/** Whether React Refresh runs: development with Metro. */
+export function refreshRuns(): boolean {
+  return reactRefresh()?.getFamilyByType !== undefined;
+}
+
+/** The family a component's versions are kept in; undefined in a release build or for a value Metro didn't export. */
+export function familyOf(type: unknown): Family | undefined {
+  return reactRefresh()?.getFamilyByType?.(type);
+}
+
+/**
+ * The newest version of a component after Fast Refresh ran its module again; the component itself when there is none
+ * newer, and in a release build.
+ */
+export function newestType<T extends object>(type: T): T {
+  return (familyOf(type)?.current as T | undefined) ?? type;
+}
+
+let redefinedListener: ((screen: object) => void) | undefined;
+
+/** Sets what runs when a module makes a screen again: Fast Refresh ran it after an edit. */
+export function onRedefined(listener: (screen: object) => void): void {
+  redefinedListener = listener;
+}
+
+/**
+ * Tells about a screen a module made, once the module ran: Metro registers its exports after it, so the family of the
+ * screen is known by then, and a new version of a screen that shows is found by it. Development only.
+ */
+export function redefined(screen: object): void {
+  if (!__DEV__ || !redefinedListener) return;
+  const listener = redefinedListener;
+  Promise.resolve().then(() => listener(screen));
+}
+
+// The id each family of screens gives the components they render, so their versions join one family too.
+const innerIds = new WeakMap<Family, string>();
+let innerCount = 0;
+
+/**
+ * Puts a component a screen or the app renders (`owner`: the screen, or the app made by createNavigation; `role`: which
+ * of its components) in a family of its own, once the owner's module ran and Metro has given the owner its family: the
+ * next version of the owner registers its component under the same id, so React Refresh keeps the component's state
+ * when the module runs again, also when the module doesn't export it. A component React Refresh knows already (its
+ * module exports it, or Babel registered it) keeps its own family. Development only.
+ */
+export function keepStateOf(owner: object, component: unknown, role = 'component'): void {
+  const refresh = reactRefresh();
+  if (!refresh?.register || component === undefined) return;
+  const register = refresh.register;
+  Promise.resolve().then(() => {
+    const family = familyOf(owner);
+    if (!family) return;
+    let id = innerIds.get(family);
+    if (id === undefined) {
+      id = `apexnative.navigation#${++innerCount}`;
+      innerIds.set(family, id);
+    }
+    register(component, `${id}.${role}`);
+  });
+}
+
+/**
+ * Makes React Refresh mount a component of the library again, not keep its state, when a new version of it comes: its
+ * hooks are the app's, which may have changed, and the library's code has no signature of them. Development only.
+ */
+export function resetOnEdit(type: object): void {
+  reactRefresh()?.createSignatureFunctionForTransform?.()(type, 'apexnative.navigation', true);
+}