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

package/src/api/screens/registerScreens.tsx

@@ -6,32 +6,39 @@ import React, {
   lazy,
   type ReactNode,
   Suspense,
-  useEffect,
   useMemo,
   useState,
 } from 'react';
-import { Platform, StyleSheet } from 'react-native';
+import { DevSettings, Platform, StyleSheet } from 'react-native';
 import ANNTurboModule from '../../adapters/NativeANNTurboModule';
 import type { NativeControllerProps } from '../../engine/nativeScreens';
 import { isButtonRoot } from '../../engine/props';
 import {
   checkArrangements,
-  type EngineArrangement,
   onScreenUnmounted,
   registerScreen as registerEngineScreen,
   type ScreenRootProps,
+  shownScreens,
 } from '../../engine/screens';
 import { screenUnmounted } from '../events/screenLifecycle';
 import { mergeOptions } from '../../engine/mergeOptions';
 import { preparedPadding } from '../../engine/slots';
-import { buildScreenOptions, type ScreenDefinition, type ScreenOptionsInput } from './defineScreen';
-import { isNativeScreen, type NativeScreen } from './nativeScreens';
+import { clearOptions, mergeOptions as sendMergeOptions } from '../../engine/commands';
+import { changeOverOwn, optionsChange } from '../../engine/optionsChange';
+import { notedScreens, ownOptionsOf } from '../../engine/rememberedOptions';
+import { openNativeScreens } from '../../engine/nativeScreens';
+import { placeOf } from '../../engine/places';
+import { propsOf } from '../../engine/props';
+import { familyOf, newestType, onRedefined } from '../../engine/refresh';
 import {
-  type Arrangement,
-  isArrangement,
-  type ScreenArrangement,
-  toEngineArrangement,
-} from './arrangement';
+  buildScreenOptions,
+  definitionOf,
+  ownDefinitionOf,
+  type ScreenDefinition,
+  type ScreenOptionsInput,
+} from './defineScreen';
+import { isNativeScreen, type NativeScreen, type NativeScreenHookProps } from './nativeScreens';
+import { type Arrangement, isArrangement, toEngineArrangement } from './arrangement';
 import { type ErrorFallbackProps, ScreenBoundary } from './ScreenBoundary';
 import ANNSafeAreaView from '../safeArea/ANNSafeAreaViewNativeComponent';
 
@@ -98,6 +105,125 @@ export interface ScreenSet {
 // The root of a screen tells when it unmounts: what the screen left behind goes.
 onScreenUnmounted(screenUnmounted);
 
+// The screens of defineScreen by name, in development: what `screens` gives (a lazy screen's module once loaded) and
+// the options of its group.
+const editable = new Map<
+  string,
+  { screen: () => unknown; groupOptions: ScreenOptionsInput<object> | undefined }
+>();
+
+onRedefined(applyEdit);
+
+// Fast Refresh ran the module of a screen again: the screens of it that show take what the edit changed in their
+// options, as a command would have shown them. The family's newest is still the version before the edit here, as React
+// Refresh moves it on only after the update.
+function applyEdit(next: object) {
+  const family = familyOf(next);
+  const edited = ownDefinitionOf(next) ?? (isNativeScreen(next) ? next : undefined);
+  if (!family || !edited) return;
+  for (const [name, { screen, groupOptions }] of editable) {
+    const current = screen();
+    if (current === undefined || familyOf(current) !== family) continue;
+    const native = isNativeScreen(current);
+    const before = native ? newestType(current) : definitionOf(current);
+    // The screen as it was registered: its own module running, nothing edited yet.
+    if (before === edited) continue;
+    // What a native screen is made of goes to the native side when it is registered and shown: a change of it starts
+    // the app again.
+    if (native && isNativeScreen(edited) && madeOtherwise(newestType(current), edited)) {
+      DevSettings.reload('[navigation] A native screen changed its name or its useProps');
+      return;
+    }
+    applyChange(
+      name,
+      native,
+      { group: groupOptions, definition: before },
+      { group: groupOptions, definition: edited }
+    );
+  }
+}
+
+/** The options a screen is shown with: those of its group, and those of its definition over them. */
+interface ShownOptions {
+  group: ScreenOptionsInput<object> | undefined;
+  definition: { options?: ScreenOptionsInput<any> } | undefined;
+}
+
+// What an edit changed in a screen's options goes to every screen of it the native side has, a screen React hasn't
+// mounted yet too (a tab not selected yet), as a command would have shown it; only where the screen still has what
+// the definition before gave.
+function applyChange(name: string, native: boolean, before: ShownOptions, after: ShownOptions) {
+  const shown = native
+    ? openNativeScreens(name)
+    : [...new Set([...shownScreens(name), ...notedScreens(name).filter(isPlaced)])].map((id) => ({
+        id,
+        props: propsOf(id),
+      }));
+  for (const { id, props } of shown) {
+    const options = ({ group, definition }: ShownOptions) =>
+      mergeOptions(
+        buildScreenOptions(group, props),
+        buildScreenOptions(definition?.options, props)
+      );
+    const shownWith = options(before);
+    const change = optionsChange(shownWith, options(after));
+    const { merge, removed } = changeOverOwn(change, shownWith, ownOptionsOf(id) ?? shownWith);
+    if (removed.length > 0) clearOptions(id, removed);
+    if (merge) sendMergeOptions(id, merge);
+  }
+}
+
+// The screens map registered again (Fast Refresh ran the module of the app): a screen written in the map itself, a
+// definition no module exports, has no family to tell its edit, so its definition before and after are compared here.
+// The options of its group too: a group is written in the app's module, and an edit of them leaves the screen as it was.
+function applyRegisteredAgain(
+  name: string,
+  entry: unknown,
+  group: ScreenOptionsInput<object> | undefined
+) {
+  const previous = editable.get(name);
+  const before = previous?.screen();
+  if (before === undefined) return;
+  if (before === entry) {
+    if (previous!.groupOptions === group) return;
+    const native = isNativeScreen(entry);
+    const definition = native ? newestType(entry) : definitionOf(entry);
+    applyChange(name, native, { group: previous!.groupOptions, definition }, { group, definition });
+    return;
+  }
+  if (isNativeScreen(before) && isNativeScreen(entry)) {
+    if (madeOtherwise(newestType(before), entry)) {
+      DevSettings.reload('[navigation] A native screen changed its name or its useProps');
+      return;
+    }
+    applyChange(
+      name,
+      true,
+      { group: previous!.groupOptions, definition: newestType(before) },
+      { group, definition: entry }
+    );
+    return;
+  }
+  const was = definitionOf(before);
+  const now = definitionOf(entry);
+  if (!was && !now && previous!.groupOptions === group) return;
+  applyChange(
+    name,
+    false,
+    { group: previous!.groupOptions, definition: was },
+    { group, definition: now }
+  );
+}
+
+// A screen the engine knows the place of: one whose command failed after its layout was built has none.
+function isPlaced(id: string): boolean {
+  return placeOf(id) !== undefined;
+}
+
+function madeOtherwise(before: NativeScreen<any>, after: NativeScreen<any>): boolean {
+  return before.nativeName !== after.nativeName || !before.useProps !== !after.useProps;
+}
+
 export function registerScreens(sets: ScreenSet[], wrapper: ScreenWrapper = {}) {
   // The screens of every set are in one namespace: a command names a screen without its group.
   const sources = new Map<string, string>();
@@ -131,21 +257,38 @@ function registerScreen(
     return;
   }
   if (isNativeScreen(entry)) {
+    // Read on every show, the newest after Fast Refresh, as for a screen of defineScreen.
+    const screen = () => newestType(entry);
+    if (__DEV__) {
+      applyRegisteredAgain(name, entry, groupOptions);
+      editable.set(name, { screen: () => entry, groupOptions });
+    }
     registerEngineScreen(name, {
       nativeName: entry.nativeName,
       options: (props) =>
         mergeOptions(
           buildScreenOptions(groupOptions, props),
-          buildScreenOptions(entry.options, props)
+          buildScreenOptions(screen().options, props)
         ),
-      controller: entry.useProps && wrapNativeScreen(name, entry.useProps, wrapper),
-      arrangement: pairOf(name, entry.arrangement),
+      controller: entry.useProps && wrapNativeScreen(name, entry, wrapper),
+      arrangement: () => {
+        const arrangement = screen().arrangement;
+        return arrangement && toEngineArrangement(name, arrangement);
+      },
     });
     return;
   }
   // React.memo and forwardRef components are objects, so the kind of entry is told by its keys.
   if (isObject(entry) && 'load' in entry) {
     const screen = lazyScreen(entry.load);
+    if (__DEV__) {
+      // A lazy screen registered again loads its module on its next show: until then the one loaded before stands for
+      // it, so the screens of it that show take an edit of their group's options, and of their module, as before.
+      const before = editable.get(name)?.screen();
+      const loaded = () => screen.loaded() ?? before;
+      applyRegisteredAgain(name, loaded(), groupOptions);
+      editable.set(name, { screen: loaded, groupOptions });
+    }
     registerEngineScreen(name, {
       component: () => wrapScreen(name, screen.component, wrapper),
       // A command loads the screen before it reads its options.
@@ -164,32 +307,34 @@ function registerScreen(
     });
     return;
   }
-  const definition = toDefinition(entry);
+  // Read on every show: after Fast Refresh a screen of defineScreen gives its new options, key and pair.
+  const definition = () => toDefinition(entry);
+  if (__DEV__) {
+    applyRegisteredAgain(name, entry, groupOptions);
+    editable.set(name, { screen: () => entry, groupOptions });
+  }
   registerEngineScreen(name, {
-    component: () => wrapScreen(name, definition.component, wrapper),
+    component: () => wrapScreen(name, definition().component, wrapper),
     options: (props) =>
       mergeOptions(
         buildScreenOptions(groupOptions, props),
-        buildScreenOptions(definition.options, props)
+        buildScreenOptions(definition().options, props)
       ),
-    key: definition.key && ((props) => definition.key!(props)),
+    key: (props) => definition().key?.(props),
     ownRoot,
-    arrangement: pairOf(name, definition.arrangement),
+    arrangement: () => {
+      const arrangement = definition().arrangement;
+      return arrangement && toEngineArrangement(name, arrangement);
+    },
   });
 }
 
-// The pair of a screen whose `arrangement` is known at registration: checked and filled in once.
-function pairOf(
-  name: string,
-  arrangement: ScreenArrangement<any> | undefined
-): (() => EngineArrangement) | undefined {
-  if (!arrangement) return undefined;
-  const pair = toEngineArrangement(name, arrangement);
-  return () => pair;
-}
-
 function toDefinition(value: ScreenComponent | ScreenDefinition): ScreenDefinition {
-  return isObject(value) && 'component' in value ? value : { component: value };
+  // A screen of defineScreen renders as itself: React Refresh knows it by its module's export, and the version of the
+  // newest definition renders in its place.
+  const defined = definitionOf(value);
+  if (defined) return { ...defined, component: value as ScreenComponent };
+  return isObject(value) && 'component' in value ? value : { component: value as ScreenComponent };
 }
 
 /**
@@ -198,15 +343,17 @@ function toDefinition(value: ScreenComponent | ScreenDefinition): ScreenDefiniti
  * screen) waits for it in Suspense.
  */
 function lazyScreen(loadModule: () => ScreenModule | PromiseLike<ScreenModule>) {
-  let definition: ScreenDefinition | undefined;
+  // The screen the module gives; its definition is read from it each time, the newest after Fast Refresh.
+  let loaded: ScreenComponent | ScreenDefinition | undefined;
   let loading: Promise<void> | undefined;
+  const definition = () => (loaded ? toDefinition(loaded) : undefined);
   const load = (): Promise<void> | undefined => {
-    if (definition) return undefined;
+    if (loaded) return undefined;
     if (!loading) {
       loading = Promise.resolve()
         .then(loadModule)
         .then((module) => {
-          definition = toDefinition(unwrapModule(module));
+          loaded = unwrapModule(module);
         });
       loading.catch(() => {
         loading = undefined;
@@ -216,14 +363,14 @@ function lazyScreen(loadModule: () => ScreenModule | PromiseLike<ScreenModule>)
   };
   const Loaded = lazy(async () => {
     await load();
-    return { default: definition!.component };
+    return { default: definition()!.component };
   });
   function LazyScreen(props: object) {
     // The same component for the life of the view, so that the load doesn't mount it again.
-    const [Screen] = useState(() => definition?.component ?? Loaded);
+    const [Screen] = useState(() => definition()?.component ?? Loaded);
     return <Screen {...props} />;
   }
-  return { load, definition: () => definition, component: LazyScreen };
+  return { load, definition, loaded: () => loaded, component: LazyScreen };
 }
 
 function unwrapModule(loaded: ScreenModule): ScreenComponent | ScreenDefinition {
@@ -297,15 +444,11 @@ function wrapScreen(name: string, Screen: ScreenComponent, wrapper: ScreenWrappe
  */
 function wrapNativeScreen(
   name: string,
-  useProps: (props: object) => object,
+  entry: NativeScreen<any>,
   { provider: Provider, onError }: ScreenWrapper
 ): ComponentType<NativeControllerProps> {
-  function Hook({ props, onProps }: Pick<NativeControllerProps, 'props' | 'onProps'>) {
-    const result = useProps(props);
-    // After each render React committed, so the native side never shows what the app did not.
-    useEffect(() => onProps(result));
-    return null;
-  }
+  // The screen's own component runs the hook: Fast Refresh puts a new version of it in place.
+  const Hook = entry as unknown as ComponentType<NativeScreenHookProps<object>>;
   function NativeScreenProps({
     componentId,
     props,

package/src/api/theme/theme.ts

@@ -135,6 +135,11 @@ export function setTheme(next: NavigationTheme) {
   listeners.forEach((listener) => listener());
 }
 
+/** The direction of the app now: the config's, or the one `setDirection` gave since. */
+export function getDirection(): NavigationDirection | undefined {
+  return direction;
+}
+
 /** Changes the direction of the app: the bars, the transitions and the swipe back follow at once. */
 export function setDirection(next: NavigationDirection) {
   direction = next;

package/src/engine/commands.ts

@@ -9,15 +9,17 @@ import { whenNativeScreensReady } from './nativeScreens';
 import { commands as native } from './native';
 import { toNativeOptions } from './options';
 import { dropReactRenderMeasures } from './reactMeasures';
-import { columnOf, forgetPlace, notePlaces, placeOf, stackOfColumn } from './places';
+import { columnOf, forgetPlace, layoutsOf, notePlaces, placeOf, stackOfColumn } from './places';
 import { forgetProps } from './props';
 import {
   forgetMergedOptions,
+  forgetMergedPaths,
+  noteMergedOwnOptions,
   rememberMergedOptions,
   rootGoesOut,
   sentRoot,
 } from './rememberedOptions';
-import { afterLoading } from './screens';
+import { afterLoading, hasRoot, isReactScreen } from './screens';
 import { holdSlot, isSlotName, removeSlots, showSlot, type SlotFrame } from './slots';
 import { forgetTabsScreen, showScreensFrom } from './tabs';
 
@@ -122,7 +124,7 @@ export function setRoot(root: LayoutRoot): Promise<string> {
 
 export function setDefaultOptions(options: Options): void {
   rememberDefaultOptions(options);
-  native.setDefaultOptions(toNativeOptions(options));
+  native.setDefaultOptions(toNativeOptions(options, 'defaultOptions'));
 }
 
 // The show commands that wait in JS, by number: for lazy screens to load, for the first props of native screens, for a
@@ -141,9 +143,10 @@ const preparedScreens = new Set<string>();
  * engine remembers them by the node's id, so the root set again for a new launch of the native side shows them too.
  */
 export function mergeOptions(componentId: string, options: Options): void {
-  const nativeOptions = toNativeOptions(options);
+  const nativeOptions = toNativeOptions(options, componentId);
   const send = () => {
     rememberMergedOptions(componentId, options);
+    noteMergedOwnOptions(componentId, options);
     native.mergeOptions(componentId, nativeOptions);
   };
   const prepared =
@@ -152,6 +155,24 @@ export function mergeOptions(componentId: string, options: Options): void {
   else heldMerges.push({ id: componentId, after: shows, send });
 }
 
+/**
+ * Takes the options at the paths, such as `['topBar', 'subtitle']`, out of the own options of a node, so it shows what
+ * the layouts around it and the defaults give there (Fast Refresh, development). It waits for the shows as a merge does.
+ */
+export function clearOptions(componentId: string, paths: readonly string[][]): void {
+  const send = () => {
+    forgetMergedPaths(componentId, paths);
+    native.clearOptions(
+      componentId,
+      paths.map((path) => path.join('.'))
+    );
+  };
+  const prepared =
+    preparedScreens.has(componentId) && !heldMerges.some(({ id }) => id === componentId);
+  if (waitingShows.size === 0 || prepared) send();
+  else heldMerges.push({ id: componentId, after: shows, send });
+}
+
 // Runs a show command; the function `run` gets lets the mergeOptions made after the show go, once it went out. It is
 // called again when the command ends, so a command that fails before it goes out lets them go too.
 function show<Result>(run: (goneOut: () => void) => Promise<Result>): Promise<Result> {
@@ -225,19 +246,44 @@ export function push(
         from?.stack ?? null,
         (from?.index ?? 0) + 1,
         from?.menu,
-        from?.layer
+        from?.layer,
+        layoutsOf(componentId)
       );
       return whenNativeScreensReady([node], () =>
-        sendPush(commandId, componentId, node, prepares, wanted, goneOut).then((shownId) => {
-          // A screen with a key went back to the one with the same key: the new screen never shows.
-          if (shownId !== node.id) forgetNeverShown(node.id);
-          return shownId;
-        })
+        sendPush(commandId, componentId, node, prepares, wanted, goneOut).then(
+          (shownId) => {
+            // A screen with a key went back to the one with the same key: the new screen never shows.
+            if (shownId !== node.id) forgetNeverShown(node.id);
+            return shownId;
+          },
+          (error: unknown) => {
+            if (rendersAtPress(node)) forgetUnmountedPreview(node.id);
+            throw error;
+          }
+        )
       );
     })
   );
 }
 
+// A preview's React screen with a root of its own renders only once the view is pressed (iOS): one whose preview went
+// before that never mounts. A screen of the one tree mounts with its slot, a native screen has no root.
+function rendersAtPress(node: LayoutNode): boolean {
+  return node.data.options?.preview?.nativeID !== undefined && isReactScreen(node.data.name ?? '');
+}
+
+// A root started at a press that came just before the preview went can reach JavaScript after its push failed: without
+// its props it would render the screen with none. Its notes go after this time, when no root of it has mounted by
+// then; one that has clears them as it unmounts.
+const PREVIEW_FORGET_DELAY = 1000;
+
+function forgetUnmountedPreview(screenId: string): void {
+  if (hasRoot(screenId)) return;
+  setTimeout(() => {
+    if (!hasRoot(screenId)) forgetNeverShown(screenId);
+  }, PREVIEW_FORGET_DELAY);
+}
+
 // Everything a push noted for a screen that never mounts, which an unmount would clear.
 function forgetNeverShown(screenId: string): void {
   forgetProps(screenId);
@@ -363,7 +409,8 @@ export function setStackRoot(componentId: string, children: Layout[]): Promise<s
           from?.stack ?? null,
           index,
           from?.menu,
-          from?.layer
+          from?.layer,
+          layoutsOf(componentId)
         )
       );
       return whenNativeScreensReady(nodes, () =>
@@ -383,7 +430,17 @@ export function showInColumn(componentId: string, column: string, layout: Layout
       showScreensFrom(componentId, node);
       const from = placeOf(componentId);
       const at = columnPlace(componentId, column);
-      notePlaces(node, from?.container ?? 'root', at.stack, at.index, from?.menu, from?.layer);
+      // In the split view of the screen it comes from, and in the column's stack.
+      const within = at.stack ? [...layoutsOf(componentId), at.stack] : layoutsOf(componentId);
+      notePlaces(
+        node,
+        from?.container ?? 'root',
+        at.stack,
+        at.index,
+        from?.menu,
+        from?.layer,
+        within
+      );
       return whenNativeScreensReady([node], () =>
         inOrder(() =>
           sendShow(goneOut, () => native.showInColumn(commandId, componentId, column, node))
@@ -431,7 +488,7 @@ export function dismissModal(componentId: string, options?: Options): Promise<st
   dropReactRenderMeasures();
   const commandId = nextId('dismissModal');
   return inOrder(() =>
-    native.dismissModal(commandId, componentId, options && toNativeOptions(options))
+    native.dismissModal(commandId, componentId, options && toNativeOptions(options, componentId))
   );
 }
 

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);