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

package/src/engine/screens.tsx

@@ -2,7 +2,7 @@ import React, { type ComponentType, useCallback, useEffect, useSyncExternalStore
 import { AppRegistry } from 'react-native';
 import type { Options } from '../interfaces/Options';
 import { forgetPlace } from './places';
-import { forgetProps, propsOf, watchProps } from './props';
+import { forgetProps, isOptionsComponent, propsOf, watchProps } from './props';
 import { forgetMergedOptions } from './rememberedOptions';
 import { hasSlot } from './slots';
 import type { NativeControllerProps } from './nativeScreens';
@@ -52,14 +52,50 @@ export type EngineScreen =
 /** What the root of a React screen renders: the screen's id, and the props the command gave it. */
 export type ScreenRootProps = { componentId: string } & Record<string, unknown>;
 
+/**
+ * What React Native gives the root of a React screen: the screen's id, its root tag (none in a slot of the app's one
+ * tree), and the props the native side gives that root, a tab cell's `tabIndex`, `selected`, `badge`, `dot` and
+ * `dotColor`.
+ */
+export type NativeRootProps = { componentId: string; rootTag?: number } & Record<string, unknown>;
+
 const screens = new Map<string, EngineScreen>();
-const roots = new Map<string, ComponentType<{ componentId: string; rootTag?: number }>>();
+const roots = new Map<string, ComponentType<NativeRootProps>>();
 let unmounted: ((screenId: string) => void) | undefined;
-// The React root that shows each screen, by its root tag. After a JavaScript reload React Native starts the roots of
-// the old screens again in the new runtime, under the ids the new screens get too, and unmounts them once the new ones
-// show; their root tags are older, as the native side counts them up for as long as the app runs. A slot of the app's
-// one tree has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
-const owners = new Map<string, number>();
+// The React roots mounted under each id, by their root tags. One id can have several: after a JavaScript reload React
+// Native starts the roots of the old screens again in the new runtime, under the ids the new screens get too, and
+// unmounts them once the new ones show; a component of the default or a stack's options has one id and a root in the
+// bar of every screen that shows it. The id lets its props go only with the last of them. A slot of the app's one tree
+// has no tag: while the one tree shows a screen with the id, no root of that id lets it go.
+const owners = new Map<string, Set<number>>();
+// The screens that show by their ids: the name, and how many roots or slots of the id are mounted (a component of the
+// options has a root in the bar of every screen that shows it).
+const shown = new Map<string, { name: string; mounts: number }>();
+
+/**
+ * Notes a screen as shown, a React root or slot of it or the controller of a native screen, until the function it
+ * gives is called.
+ */
+export function noteShown(componentId: string, name: string): () => void {
+  const entry = shown.get(componentId);
+  if (entry?.name === name) entry.mounts++;
+  else shown.set(componentId, { name, mounts: 1 });
+  return () => {
+    const current = shown.get(componentId);
+    if (current?.name !== name) return;
+    if (--current.mounts === 0) shown.delete(componentId);
+  };
+}
+
+/** The ids of the screens with the name that show now. */
+export function shownScreens(name: string): string[] {
+  return [...shown].filter(([, entry]) => entry.name === name).map(([id]) => id);
+}
+
+/** Whether a React root of the screen with the id is mounted now (a slot of the app's one tree doesn't count). */
+export function hasRoot(componentId: string): boolean {
+  return owners.has(componentId);
+}
 
 /** What runs when the root of a screen unmounts: the screen is gone. */
 export function onScreenUnmounted(listener: (screenId: string) => void): void {
@@ -192,20 +228,29 @@ export function isReactScreen(name: string): boolean {
   return screen !== undefined && 'component' in screen;
 }
 
+/**
+ * The props a screen's component renders with: those a command left under its id ([stored]), the props the native side
+ * gave its root over them ([root]: a tab cell's state, which the docs promise arrives on top of `passProps`), and its
+ * id. The root tag stays with the root.
+ */
+export function screenProps(stored: object, root: NativeRootProps): ScreenRootProps {
+  const props: ScreenRootProps = { ...stored, ...root, componentId: root.componentId };
+  delete props.rootTag;
+  return props;
+}
+
 /**
  * The root a React screen runs in: the screen with the props a command left for it under its id, and the new ones when
- * options give its id new props. React Native gives a root only its id (and its own root props, which stay here); the
- * slot of the app's one tree renders the same root.
+ * options give its id new props, under the props the native side gives the root ([screenProps]). The slot of the app's
+ * one tree renders the same root.
  */
-export function screenRoot(
-  name: string
-): ComponentType<{ componentId: string; rootTag?: number }> | undefined {
+export function screenRoot(name: string): ComponentType<NativeRootProps> | undefined {
   const screen = screens.get(name);
   if (!screen || !('component' in screen)) return undefined;
   let root = roots.get(name);
   if (!root) {
     const Screen = screen.component();
-    root = function ScreenRoot(rootProps: { componentId: string; rootTag?: number }) {
+    root = function ScreenRoot(rootProps: NativeRootProps) {
       // In the app's one tree the slot renders the root, without a tag of its own.
       const { componentId, rootTag } = rootProps;
       const watch = useCallback(
@@ -213,24 +258,34 @@ export function screenRoot(
         [componentId]
       );
       const props = useSyncExternalStore(watch, () => propsOf(componentId));
+      useEffect(() => noteShown(componentId, name), [componentId]);
       useEffect(() => {
-        if (rootTag !== undefined && rootTag > (owners.get(componentId) ?? -1)) {
-          owners.set(componentId, rootTag);
+        if (rootTag !== undefined) {
+          const tags = owners.get(componentId) ?? new Set<number>();
+          tags.add(rootTag);
+          owners.set(componentId, tags);
         }
         return () => {
-          // An old root of the same id leaves the screen alone, and so does any root while the one tree still has a slot
-          // with the id: a later screen under the id, the restarted root of a screen after a reload into the one tree
-          // (its slot may mount only once the app's provider lets it), the screen rendering again under the provider.
-          if (rootTag !== undefined && owners.get(componentId) !== rootTag) return;
+          // A root while another root of the id is mounted leaves the screen alone, and so does any root while the one
+          // tree still has a slot with the id: a later screen under the id, the restarted root of a screen after a
+          // reload into the one tree (its slot may mount only once the app's provider lets it), the screen rendering
+          // again under the provider.
+          const tags = owners.get(componentId);
+          if (rootTag !== undefined && tags) {
+            tags.delete(rootTag);
+            if (tags.size > 0) return;
+          }
           if (hasSlot(componentId)) return;
           owners.delete(componentId);
-          forgetProps(componentId);
+          // A component the library named in options keeps its props for the next root under its id (the node shows
+          // it again, or another screen shows the same default): they go with the node.
+          if (!isOptionsComponent(componentId)) forgetProps(componentId);
           forgetPlace(componentId);
           forgetMergedOptions(componentId);
           unmounted?.(componentId);
         };
       }, [componentId, rootTag]);
-      return <Screen {...props} componentId={componentId} />;
+      return <Screen {...screenProps(props, rootProps)} />;
     };
     root.displayName = `ScreenRoot(${name})`;
     roots.set(name, root);

package/src/interfaces/ComponentEvents.ts

@@ -10,7 +10,7 @@ export type ComponentType =
 
 /** The fields every appearance event has. */
 interface ComponentAppearanceEvent {
-  /** The id of the component: the screen, or the screen the bar component belongs to. */
+  /** The id of the component: of the screen, or the bar component's own id. */
   componentId: string;
   /** The name of the component: for a screen, its name without any internal prefix. */
   componentName: string;
@@ -60,7 +60,7 @@ export interface NavigationButtonPressedEvent {
    * `ApexNavigation.back`; the hardware back of a modal has `ApexNavigation.hardwareBackButton`.
    */
   buttonId: string;
-  /** (iOS) For a button with `toggle`: its new state, already written into the options of the screen. */
+  /** (iOS) For a button with `toggle`: its new state, which the screen keeps. */
   selected?: boolean;
 }
 
@@ -95,8 +95,8 @@ export interface SheetDetentChangedEvent {
   /** The id of the visible screen of the modal. */
   componentId: string;
   /**
-   * The detent the sheet stopped at: `'medium'`, `'large'`, or a height (points on iOS, dp on Android). `'content'`
-   * is sent on iOS for a detent that fits the content; Android names such a detent `'medium'`.
+   * The detent the sheet stopped at: `'medium'`, `'large'`, `'content'` (the detent that fits the content), or a
+   * height (points on iOS, dp on Android).
    */
   detent: 'medium' | 'large' | 'content' | number;
 }

package/src/interfaces/Events.ts

@@ -54,8 +54,12 @@ export interface NavigationStateChangedEvent {
 
 /**
  * A tab was selected by the user: a press on the tab, a pick from the "More" list or a press on "More" that showed a
- * tab (iOS). It is sent after the selection, and only when the tab changed; a press on the current tab is reported by
- * `BottomTabPressedEvent` alone. Selecting a tab from code sends nothing.
+ * tab (iOS). It goes right after the `ComponentDidAppear` of the new tab's screen, before the navigation state and
+ * before the tab that was left goes back to its first screen (`popToRootOnBlur`), and only when the tab changed: a
+ * press on the selected tab or on a `selectTabOnPress: false` tab is reported by `BottomTabPressedEvent` alone.
+ * Selecting a tab from code sends nothing. A switch still running when another press, long press or choice from code
+ * comes ends first, with this event, so the events of one press never mix with the next; when that tab's screen
+ * hasn't drawn yet, this event goes before its held `ComponentDidAppear`.
  */
 export interface BottomTabSelectedEvent {
   /** The index of the tab that is now selected. */
@@ -67,24 +71,28 @@ export interface BottomTabSelectedEvent {
 }
 
 /**
- * A tab was pressed, the selected one too. It is sent before the tab is selected; with `selectTabOnPress: false` it is
- * the only thing that happens. A long press sends `BottomTabLongPressedEvent` instead.
+ * A tab was pressed, on the bar or on a cell of `bottomTabs.customRow`, the selected one too. It goes first, before
+ * anything the press does. Another tab: then the switch's `ComponentWillAppear`, `ComponentDidDisappear` and
+ * `ComponentDidAppear`, then `BottomTabSelectedEvent`. The selected tab again (`wasSelected: true`): its stack goes
+ * back to its first screen with the events of the user's back (`ScreenPopped`), or, on the first screen, its content
+ * scrolls to the top; with `popToRootOnPress: false` nothing follows. With `selectTabOnPress: false` it is the only
+ * event and the selection stays. A long press sends `BottomTabLongPressedEvent` instead.
  */
 export interface BottomTabPressedEvent {
   /** The index of the tab that was pressed. */
   tabIndex: number;
   /** The id of the tabs. */
   bottomTabsId: string;
-  /** The id of the screen the tab shows: the top of its stack. */
+  /** The id of the screen the tab shows: the top of its stack, or the tab itself when it is a screen. */
   screenId?: string;
   /** Whether the tab was the selected one already; a press on the selected tab scrolls its content to the top. */
   wasSelected: boolean;
 }
 
 /**
- * A tab was pressed and held. The tab is not selected and gets no press event. On iOS it is not sent for the tabs
- * that are components (`bottomTab.component`, `bottomTabs.customRow`), for "More", or for the tab strip at the top of an
- * iPad. On Android it replaces the tooltip of the tab.
+ * A tab was pressed and held, on the bar or on a cell of `bottomTabs.customRow`. The tab is not selected and gets no
+ * press event. On iOS it is not sent for "More" or for the tab strip at the top of an iPad. On Android it replaces the
+ * tooltip of the tab.
  */
 export interface BottomTabLongPressedEvent {
   /** The index of the tab that was pressed. */
@@ -105,6 +113,16 @@ export interface SplitViewColumnsStackedEvent {
   stacked: boolean;
 }
 
+/**
+ * (iOS) A link the app dispatched (`dispatchDeepLinkURL`) that React Native's `Linking` doesn't take from the native
+ * side: on React Native 0.88 and newer, in an app whose Info.plist names a scene delegate, it takes only the links a
+ * scene opened. JavaScript hands it to `Linking` as a `url` event.
+ */
+export interface DeepLinkDispatchedEvent {
+  /** The link. */
+  url: string;
+}
+
 /**
  * A screen of the single React tree was destroyed and the slot still belongs to it: JavaScript removes the slot from
  * its tree. It is not sent for a prepared screen that was never pushed, nor when JavaScript reloads.
@@ -185,11 +203,12 @@ export type HingeState = 'closed' | 'partiallyOpen' | 'fullyOpen' | 'unknown';
  */
 export interface HingeChangedEvent {
   /**
-   * The state of the hinge. On Android `closed` means the device has no fold, or its angle is below 90 degrees.
+   * The state of the hinge. On Android `closed` means the app's window has no fold, or the angle is below 90 degrees,
+   * so a device open flat with a window off the fold (split screen) reports `closed`; Android never gives `unknown`.
    */
   state?: HingeState;
   /**
-   * The angle of the hinge in degrees (on iOS to tenths). Missing when the state is `unknown` and where the system
+   * The angle of the hinge in degrees, to tenths. Missing when the state is `unknown` and where the system
    * gives no angle.
    */
   angle?: number;

package/src/interfaces/Options.ts

@@ -107,6 +107,7 @@ export type {
   ScreenAnimationOptions,
   SharedElementTransition,
   StackAnimationOptions,
+  StackPopAnimationOptions,
   StackPushAnimationOptions,
   TopBarAnimationOptions,
   ViewAnimationOptions,

package/src/interfaces/contract/commands.json

@@ -0,0 +1,101 @@
+{
+  "description": "Every command with a promise (an async method of src/adapters/NativeANNTurboModule.ts): what it resolves with, whether the navigation state goes before its answer (`state`), and whether `ANN.CommandCompleted` follows the answer (`completed`). scripts/contract.mjs makes ios/Contract/ANNCommandContract.{h,mm} and android/.../react/CommandContract.kt from it, and fails when a command of the spec is missing here or a command here is not in the spec.",
+  "commands": [
+    {
+      "name": "setRoot",
+      "resolves": "the id of the root, once the root and the layout's modals and overlays show",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "push",
+      "resolves": "the id of the screen that shows; of a pair, the pair's id",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "preparePush",
+      "resolves": "the frame `{ width, height, padding }` of the prepared screen, or null; always null on iOS",
+      "state": false,
+      "completed": false
+    },
+    {
+      "name": "pop",
+      "resolves": "the id of the screen that went",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popTo",
+      "resolves": "the id of the screen it went back to",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "popToRoot",
+      "resolves": "the id of the first screen of the stack",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setStackRoot",
+      "resolves": "the id of the new top screen",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissModal",
+      "resolves": "the id of the modal's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllModals",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissOverlay",
+      "resolves": "the id of the overlay's root",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "dismissAllOverlays",
+      "resolves": "an empty string",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "showInColumn",
+      "resolves": "the id of the screen that shows",
+      "state": true,
+      "completed": true
+    },
+    {
+      "name": "setColumnShown",
+      "resolves": "nothing once the columns stopped moving (`undefined` on iOS, `null` on Android)",
+      "state": true,
+      "completed": false
+    },
+    {
+      "name": "getLaunchLink",
+      "resolves": "the link that launched the app, or null",
+      "state": false,
+      "completed": false
+    }
+  ]
+}

package/src/interfaces/contract/errors.json

@@ -0,0 +1,275 @@
+{
+  "description": "Every text the native side rejects a command with, or logs for a command without a promise: one sentence per case, the values in single quotes, {name} for a parameter. scripts/contract.mjs makes ios/Contract/ANNErrorTexts.{h,mm} and android/.../react/ErrorTexts.kt from it; `platforms` limits a text to one platform.",
+  "groups": [
+    {
+      "title": "Where the screen is",
+      "texts": [
+        {
+          "name": "screenNotShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not shown"
+        },
+        {
+          "name": "notInStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a stack"
+        },
+        {
+          "name": "firstScreenOfStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is the first screen of its stack"
+        },
+        {
+          "name": "notInThisStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in this stack"
+        },
+        {
+          "name": "notInModal",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a modal"
+        },
+        {
+          "name": "notInOverlay",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in an overlay"
+        },
+        {
+          "name": "notInSplitView",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is not in a split view"
+        },
+        {
+          "name": "neitherSplitViewNorStack",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' is neither in a split view nor in a stack"
+        },
+        {
+          "name": "noSuchColumn",
+          "params": ["componentId", "column"],
+          "text": "the split view of the screen '{componentId}' has no '{column}' column"
+        },
+        {
+          "name": "columnIsStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is a stack: it takes a screen, not a stack"
+        },
+        {
+          "name": "columnNotStack",
+          "params": ["componentId", "column"],
+          "text": "the '{column}' column of the split view of the screen '{componentId}' is not a stack"
+        },
+        {
+          "name": "noScreensForStack",
+          "params": ["componentId"],
+          "text": "there are no screens to put in the stack of the screen '{componentId}'"
+        },
+        {
+          "name": "alreadyShown",
+          "params": ["componentId"],
+          "text": "the screen '{componentId}' shows already: an id goes to one screen"
+        }
+      ]
+    },
+    {
+      "title": "Root, modals, the app",
+      "texts": [
+        {
+          "name": "setRootReplaced",
+          "params": ["rootId"],
+          "text": "setRoot was replaced by a newer setRoot before the root '{rootId}' finished showing"
+        },
+        {
+          "name": "rootDestroyed",
+          "params": ["rootId"],
+          "text": "the root '{rootId}' was destroyed before it showed"
+        },
+        {
+          "name": "modalWithoutRoot",
+          "params": ["componentId"],
+          "text": "the modal '{componentId}' can't be dismissed: there is no root under it"
+        },
+        {
+          "name": "nowhereToShow",
+          "params": [],
+          "text": "the navigation has nowhere to show screens: the app has no activity or window"
+        }
+      ]
+    },
+    {
+      "title": "Native screens",
+      "texts": [
+        {
+          "name": "nativeScreenNotRegistered",
+          "params": ["name"],
+          "text": "no native screen is registered as '{name}'"
+        },
+        {
+          "name": "nativeScreenNotCreated",
+          "params": ["name"],
+          "text": "the native screen '{name}' could not be created: its creator returned nothing"
+        },
+        {
+          "name": "nativeCallReloaded",
+          "params": ["name", "componentId"],
+          "text": "JavaScript reloaded before the call '{name}' of the screen '{componentId}' was answered",
+          "doc": "The error of a call of a native screen whose JavaScript reloaded before it answered."
+        },
+        {
+          "name": "nativeCallNotRunning",
+          "params": ["name", "componentId"],
+          "text": "the navigation is not running: the call '{name}' of the screen '{componentId}' can't be answered",
+          "doc": "The error of a call of a native screen while no JavaScript can answer it."
+        }
+      ]
+    },
+    {
+      "title": "The layout",
+      "texts": [
+        {
+          "name": "unknownNodeType",
+          "params": ["type"],
+          "text": "the layout has a node of unknown type '{type}'"
+        },
+        {
+          "name": "nodeWithoutId",
+          "params": ["type"],
+          "text": "the layout has a node of type '{type}' without an id"
+        },
+        {
+          "name": "sideMenuChild",
+          "params": ["menuId", "type"],
+          "text": "the side menu '{menuId}' has a child of type '{type}': it takes SideMenuLeft, SideMenuCenter and SideMenuRight"
+        },
+        {
+          "name": "stackTakesScreens",
+          "params": ["stackId", "type"],
+          "text": "the stack '{stackId}' takes screens, not a '{type}'"
+        },
+        {
+          "name": "emptyStack",
+          "params": ["stackId"],
+          "text": "the stack '{stackId}' has no screens"
+        },
+        {
+          "name": "emptyTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have no tabs"
+        },
+        {
+          "name": "tooManyTabs",
+          "params": [
+            "tabsId",
+            {
+              "name": "count",
+              "type": "int"
+            }
+          ],
+          "text": "the tabs '{tabsId}' have {count} tabs: Android shows at most 5",
+          "doc": "Only Android checks it: its tab bar shows at most 5 tabs."
+        },
+        {
+          "name": "splitViewColumns",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' needs its primary and its secondary column"
+        },
+        {
+          "name": "pairUnsupported",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs iOS 27.1 and an app built with its SDK",
+          "doc": "Only iOS checks it: Android has pairs on every version."
+        },
+        {
+          "name": "pairNeedsTwoScreens",
+          "params": ["pairId"],
+          "text": "the pair '{pairId}' needs two screens: its primary and its secondary"
+        },
+        {
+          "name": "nodeWithoutName",
+          "params": ["type", "nodeId"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' without a name"
+        },
+        {
+          "name": "rootMissing",
+          "params": [],
+          "text": "the layout of setRoot has no root"
+        },
+        {
+          "name": "tabsInTabs",
+          "params": ["tabsId"],
+          "text": "the tabs '{tabsId}' have a tab of type 'BottomTabs': tabs don't go inside tabs"
+        },
+        {
+          "name": "sideMenuSides",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' takes one SideMenuCenter and at most one SideMenuLeft and one SideMenuRight"
+        },
+        {
+          "name": "sideChildCount",
+          "params": ["sideId", "menuId"],
+          "text": "the side '{sideId}' of the side menu '{menuId}' needs exactly one child"
+        },
+        {
+          "name": "sideMenuInSide",
+          "params": ["menuId"],
+          "text": "the side menu '{menuId}' has a side menu in a side: a side menu doesn't go inside a side menu"
+        },
+        {
+          "name": "sideOutsideMenu",
+          "params": ["nodeId", "type"],
+          "text": "the layout has a node '{nodeId}' of type '{type}' outside a side menu"
+        },
+        {
+          "name": "splitViewInColumn",
+          "params": ["splitViewId"],
+          "text": "the split view '{splitViewId}' has a column of type 'SplitView': a split view doesn't go inside a split view"
+        },
+        {
+          "name": "idGivenTwice",
+          "params": ["nodeId"],
+          "text": "the layout gives the id '{nodeId}' to two nodes"
+        }
+      ]
+    },
+    {
+      "title": "Options, previews, any other failure",
+      "texts": [
+        {
+          "name": "unreadableOption",
+          "params": ["path", "componentId"],
+          "text": "the option '{path}' of the screen '{componentId}' has a value the navigation can't read"
+        },
+        {
+          "name": "unreadableDefaultOption",
+          "params": ["path"],
+          "text": "the option '{path}' of the default options has a value the navigation can't read",
+          "doc": "An unreadable value of `setDefaultOptions`: the default options belong to no screen."
+        },
+        {
+          "name": "previewGone",
+          "params": ["previewId"],
+          "text": "the preview '{previewId}' went without being opened"
+        },
+        {
+          "name": "couldNot",
+          "params": ["what", "reason"],
+          "text": "could not {what}: {reason}",
+          "doc": "Any other failure: what could not be done and why, `could not <what>: <reason>`."
+        },
+        {
+          "name": "notDoneYet",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core doesn't do it yet",
+          "doc": "A command whose part of the native core is not written yet."
+        },
+        {
+          "name": "notAnswered",
+          "params": ["method"],
+          "text": "could not run '{method}': the native core let it go without an answer",
+          "doc": "A command that nothing in the native core answered: what took it let it go, or nothing took it.",
+          "platforms": ["ios"]
+        }
+      ]
+    }
+  ]
+}