@apexnative/navigation 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/api/screens/nativeScreens.ts

@@ -1,3 +1,5 @@
+import { useEffect } from 'react';
+import { redefined, resetOnEdit } from '../../engine/refresh';
 import type { ScreenArrangement } from './arrangement';
 import type { ScreenOptionsInput } from './defineScreen';
 
@@ -30,7 +32,9 @@ export interface NativeScreenDefinition<Props extends object> {
 
 /**
  * A native screen for `screens`: commands and layouts name it like any other screen, and its props go to the native
- * creator. `nativeName` is the name it is registered under natively (`ApexNavigation.registerNativeScreen`).
+ * creator. `nativeName` is the name it is registered under natively (`ApexNavigation.registerNativeScreen`). It is a
+ * component that runs `useProps`, so a file that exports only its screens updates by Fast Refresh, the hook and the
+ * options too.
  *
  * @example
  * const Settings = nativeScreen('Settings', {
@@ -49,10 +53,42 @@ export function nativeScreen<Props extends object = {}>(
   nativeName: string,
   definition: NativeScreenDefinition<Props> = {}
 ): NativeScreen<Props> {
-  const { options, useProps, arrangement } = definition;
-  return { [NATIVE_SCREEN]: true, nativeName, options, useProps, arrangement };
+  const { options, useProps = noProps, arrangement } = definition;
+  // A component that runs the hook, so that a file exporting only its screens stays a boundary of Fast Refresh: React
+  // Refresh puts the new version in place, with the edited hook.
+  function NativeScreen({ props, onProps }: NativeScreenHookProps<Props>) {
+    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;
+  }
+  const screen = Object.assign(NativeScreen, {
+    [NATIVE_SCREEN]: true as const,
+    nativeName,
+    options,
+    useProps: definition.useProps,
+    arrangement,
+  });
+  // The hook is the app's and may have other hooks after an edit: its new version mounts anew.
+  resetOnEdit(screen);
+  redefined(screen);
+  return screen;
+}
+
+function noProps(): object {
+  return {};
+}
+
+/** What the component of a native screen renders with: the props of the command, and where the hook's result goes. */
+export interface NativeScreenHookProps<Props> {
+  props: Props;
+  onProps(result: object): void;
 }
 
 export function isNativeScreen(value: unknown): value is NativeScreen<any> {
-  return typeof value === 'object' && value !== null && NATIVE_SCREEN in value;
+  return (
+    (typeof value === 'function' || typeof value === 'object') &&
+    value !== null &&
+    NATIVE_SCREEN in value
+  );
 }

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

@@ -13,6 +13,8 @@ import { columnOf, forgetPlace, layoutsOf, notePlaces, placeOf, stackOfColumn }
 import { forgetProps } from './props';
 import {
   forgetMergedOptions,
+  forgetMergedPaths,
+  noteMergedOwnOptions,
   rememberMergedOptions,
   rootGoesOut,
   sentRoot,
@@ -144,6 +146,7 @@ export function mergeOptions(componentId: string, options: Options): void {
   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> {

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 {

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,4 +1,4 @@
-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, rememberOptionsComponent, setProps } from './props';
@@ -162,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
+  );
+}