@applicaster/zapp-react-native-utils 16.0.0-rc.80 → 16.0.0-rc.82

package/actionsExecutor/ActionExecutorContext.tsx

@@ -9,7 +9,7 @@ import { ActionExecutionContext, ActionHandler } from "./types";
 import { batchRemoveAllFromNamespaceForStorage } from "../zappFrameworkUtils/localStorageHelper";
 import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
 
-import { useNavigation, useRivers } from "../reactHooks";
+import { useNavigation, usePresentScreen, useRivers } from "../reactHooks";
 import { useContentTypes } from "@applicaster/zapp-react-native-redux/hooks";
 import { useSubscriberFor } from "../reactHooks/useSubscriberFor";
 import { APP_EVENTS } from "../appUtils/events";
@@ -25,6 +25,7 @@ import {
   localStorageRemoveAction,
   localStorageSetAction,
   localStorageToggleFlagAction,
+  createPresentScreenAction,
   openBottomSheetAction,
   refreshComponentAction,
   screenSetVariableAction,
@@ -157,6 +158,7 @@ export function withActionExecutor(Component) {
     const navigator = useNavigation();
     const rivers = useRivers();
     const contentTypes = useContentTypes();
+    const presentScreen = usePresentScreen();
 
     const handlers = useMemo(() => {
       return {
@@ -191,6 +193,13 @@ export function withActionExecutor(Component) {
       );
     }, [navigator, rivers, contentTypes]);
 
+    useEffect(() => {
+      return _actionExecutor.registerAction(
+        ACTION_TYPES.PRESENT_SCREEN,
+        createPresentScreenAction(presentScreen)
+      );
+    }, [presentScreen]);
+
     useEffect(() => {
       return _actionExecutor.registerAction(
         ACTION_TYPES.GO_BACK,

package/actionsExecutor/actions/__tests__/presentScreen.test.ts

@@ -0,0 +1,127 @@
+import { createPresentScreenAction } from "../presentScreen";
+import { ActionResult } from "../../ActionExecutor";
+
+const contextEntry = { id: "context-entry" } as any;
+
+const succeeded = { success: true, cancelled: false };
+
+const cancelled = { success: false, cancelled: true };
+
+describe("presentScreenAction", () => {
+  let presentScreen: jest.Mock;
+  let presentScreenAction: ReturnType<typeof createPresentScreenAction>;
+
+  beforeEach(() => {
+    presentScreen = jest.fn().mockResolvedValue(succeeded);
+    presentScreenAction = createPresentScreenAction(presentScreen);
+  });
+
+  it("presents the screen named by typeMapping", async () => {
+    await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: undefined,
+    });
+  });
+
+  it("fails without presenting anything when typeMapping is missing", async () => {
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: {},
+    });
+
+    expect(result).toBe(ActionResult.Error);
+    expect(presentScreen).not.toHaveBeenCalled();
+  });
+
+  it("resolves the '@{entry/}' token to the entry from the execution context", async () => {
+    await presentScreenAction(
+      {
+        type: "presentScreen",
+        options: { typeMapping: "parent_lock", entry: "@{entry/}" },
+      },
+      { entry: contextEntry }
+    );
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: contextEntry,
+    });
+  });
+
+  it("presents an entry supplied inline in the options", async () => {
+    const inlineEntry = { id: "inline-entry" } as any;
+
+    await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock", entry: inlineEntry },
+    });
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: inlineEntry,
+    });
+  });
+
+  it("fails without presenting anything when the entry option is not an object", async () => {
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock", entry: "not-an-entry" as any },
+    });
+
+    expect(result).toBe(ActionResult.Error);
+    expect(presentScreen).not.toHaveBeenCalled();
+  });
+
+  it("succeeds when the presented screen reports success", async () => {
+    presentScreen.mockResolvedValue(succeeded);
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("cancels the action chain when the presented screen is cancelled", async () => {
+    presentScreen.mockResolvedValue(cancelled);
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Cancel);
+  });
+
+  it("cancels the action chain when the presented screen reports failure", async () => {
+    presentScreen.mockResolvedValue({ success: false, cancelled: false });
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Cancel);
+  });
+
+  it("errors when the screen could not be presented at all", async () => {
+    presentScreen.mockResolvedValue({
+      success: false,
+      cancelled: false,
+      error: "can not resolve screen type mapping: parent_lock",
+    });
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Error);
+  });
+});

package/actionsExecutor/actions/index.ts

@@ -27,6 +27,8 @@ export { screenToggleFlagAction } from "./screenToggleFlag";
 
 export { createNavigateToScreenAction } from "./navigateToScreen";
 
+export { createPresentScreenAction } from "./presentScreen";
+
 export { createGoBackAction } from "./goBack";
 
 export { createGoHomeAction } from "./goHome";

package/actionsExecutor/actions/presentScreen.ts

@@ -0,0 +1,78 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler, ActionExecutionContext } from "../types";
+import type { PresentScreenFn } from "../../reactHooks/navigation/usePresentScreen";
+import { createLogger } from "../../logger";
+
+const { log_error } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Options for the presentScreen action.
+ */
+export interface PresentScreenOptions {
+  /** The screen type to present (from content types mapping) */
+  typeMapping: string;
+
+  /**
+   * Entry to present the screen with. Can be:
+   * - "@{entry/}" to use the context entry
+   * - A ZappEntry object
+   * - undefined to present the screen without an entry
+   */
+  entry?: "@{entry/}" | ZappEntry;
+}
+
+/**
+ * Creates a present-screen action handler with the provided dependencies.
+ *
+ * Unlike navigateToScreen, this action does not return until the presented
+ * screen reports a result, so a screen that gates the flow (a parental lock,
+ * for example) can stop the remaining actions by being cancelled.
+ *
+ * @param presentScreen - Presents a screen as a modal and resolves with its result
+ * @returns An action handler that presents a screen and awaits its outcome
+ */
+export function createPresentScreenAction(
+  presentScreen: PresentScreenFn
+): ActionHandler<PresentScreenOptions> {
+  return async function presentScreenAction(
+    action,
+    context?: ActionExecutionContext
+  ): Promise<ActionResult> {
+    const typeMapping = action.options?.typeMapping;
+
+    if (!typeMapping) {
+      log_error("presentScreen: typeMapping option is missing");
+
+      return ActionResult.Error;
+    }
+
+    const entrySource = action.options?.entry;
+
+    const entry = entrySource
+      ? entrySource === "@{entry/}"
+        ? context?.entry
+        : entrySource
+      : undefined;
+
+    if (entry && typeof entry !== "object") {
+      log_error(
+        `presentScreen: entry option is not an object, entry: ${entry}`
+      );
+
+      return ActionResult.Error;
+    }
+
+    const result = await presentScreen({ typeMapping, entry });
+
+    if (result.error) {
+      return ActionResult.Error;
+    }
+
+    // Anything short of success stops the remaining actions in the chain.
+    return result.success ? ActionResult.Success : ActionResult.Cancel;
+  };
+}

package/actionsExecutor/consts.ts

@@ -9,6 +9,7 @@ export const ACTION_TYPES = {
   PRESENT_SUB_MENU: "presentSubMenu",
   SEND_CLOUD_EVENT: "sendCloudEvent",
   NAVIGATE_TO_SCREEN: "navigateToScreen",
+  PRESENT_SCREEN: "presentScreen",
   GO_BACK: "goBack",
   GO_HOME: "goHome",
   SHOW_TOAST: "showToast",

package/configurationUtils/__tests__/manifestKeyParser.test.ts

@@ -176,6 +176,27 @@ describe("getAllSpecificStyles", () => {
       });
     });
 
+    it("should normalize Studio focus alias onto focused state", () => {
+      const outStyles = {};
+
+      const configuration = {
+        button_style_focus_background_color: "#FF3B30",
+      };
+
+      getAllSpecificStyles({
+        componentName: "button",
+        subComponentName: "",
+        configuration,
+        outStyles,
+      });
+
+      expect(outStyles.focused).toEqual({
+        backgroundColor: "#FF3B30",
+      });
+
+      expect(outStyles.focus).toBeUndefined();
+    });
+
     it("should handle selected state", () => {
       const outStyles = {};
 

package/configurationUtils/__tests__/modalBlocksParser.test.ts

@@ -104,4 +104,157 @@ describe("parseModalBlocksConfiguration", () => {
     expect(result.button.title).toEqual({ default: {} });
     expect(result.action.leadingIcon).toEqual({ default: {} });
   });
+
+  it("should map Studio item.background.focus.* onto focused state", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "item.background.default.background_color": "transparent",
+        "item.background.focus.background_color": "#FF3B30",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.background.default).toEqual(
+      expect.objectContaining({
+        backgroundColor: "transparent",
+      })
+    );
+
+    expect(result.item.background.focused).toEqual(
+      expect.objectContaining({
+        backgroundColor: "#FF3B30",
+      })
+    );
+  });
+
+  it("should accept Studio text_label1 keys without underscore before digit", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "item.text_label1.font_color": "#00FF00",
+        "item.text_label1.font_size": 28,
+        "item.text_label2.font_color": "#00FFFF",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.textLabel1.default).toEqual(
+      expect.objectContaining({
+        fontColor: "#00FF00",
+        fontSize: 28,
+      })
+    );
+
+    expect(result.item.textLabel2.default).toEqual(
+      expect.objectContaining({
+        fontColor: "#00FFFF",
+      })
+    );
+  });
+
+  it("should map button.create_new_playlist_asset onto leadingIcon.asset", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "button.create_new_playlist_asset":
+          "https://placehold.co/24x24/FF00FF/FFFFFF/png?text=CN",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.button.leadingIcon.default).toEqual(
+      expect.objectContaining({
+        asset: "https://placehold.co/24x24/FF00FF/FFFFFF/png?text=CN",
+      })
+    );
+  });
+
+  it("should map item.checkbox_asset and checked_checkbox_asset onto item.checkbox", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "item.checkbox_asset":
+          "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=CB",
+        "item.checked_checkbox_asset":
+          "https://placehold.co/24x24/FFD60A/000000/png?text=CK",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.checkbox.default).toEqual(
+      expect.objectContaining({
+        asset: "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=CB",
+        checkedAsset: "https://placehold.co/24x24/FFD60A/000000/png?text=CK",
+      })
+    );
+  });
+
+  it("should map reorder/remove Studio assets onto item.actionButtons", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "reorder_playlist_item.remove_from_playlist_asset":
+          "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        "reorder_playlist_item.reorder_handle_asset":
+          "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.actionButtons.default).toEqual(
+      expect.objectContaining({
+        removeAsset: "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        dragAsset: "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      })
+    );
+  });
+
+  it("should fall back to flavor1 reorder/remove assets", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "playlist_experience_assets_flavor1.remove_from_playlist_asset":
+          "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        "playlist_experience_assets_flavor1.reorder_handle_asset":
+          "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.actionButtons.default).toEqual(
+      expect.objectContaining({
+        removeAsset: "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        dragAsset: "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      })
+    );
+  });
+
+  it("should fall back to flavor2 reorder/remove assets", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "playlist_experience_assets_flavor2.remove_from_playlist_asset":
+          "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        "playlist_experience_assets_flavor2.reorder_handle_asset":
+          "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      },
+      "playlist-experience"
+    );
+
+    expect(result.item.actionButtons.default).toEqual(
+      expect.objectContaining({
+        removeAsset: "https://placehold.co/24x24/00FF00/000000/png?text=RM",
+        dragAsset: "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      })
+    );
+  });
+
+  it("should ignore playlist-only asset keys for other theme plugins", () => {
+    const result = parseModalBlocksConfiguration(
+      {
+        "button.create_new_playlist_asset":
+          "https://placehold.co/24x24/FF00FF/FFFFFF/png?text=CN",
+        "playlist_experience_assets_flavor1.reorder_handle_asset":
+          "https://placehold.co/24x24/FF3B30/FFFFFF/png?text=RH",
+      },
+      "queue-action"
+    );
+
+    expect(result.button.leadingIcon.default?.asset).toBeUndefined();
+    expect(result.item.actionButtons.default?.dragAsset).toBeUndefined();
+  });
 });

package/configurationUtils/manifestKeyParser.ts

@@ -11,11 +11,17 @@ const currentPlatform = platformSelect({
   android_tv: "android",
 });
 
-// Do not change the order, focused_selected should be first
+// Do not change the order: focused_selected must be first, and "focus" must
+// come *after* "focused". Matching uses startsWith(state + "_"), so putting
+// "focus" first would steal focused_* / focused_selected_* keys. Adding
+// "focus" here affects every getAllSpecificStyles consumer (not only modals);
+// property names that themselves start with focus_ (e.g. focus_font_color as
+// a non-state style) would also be classified as the focus state.
 const states = [
   "focused_selected",
   "pressed",
   "focused",
+  "focus",
   "selected",
   "default",
 ];
@@ -112,6 +118,11 @@ export const getAllSpecificStyles = ({
       state = defaultKey;
     }
 
+    // Normalize Studio "focus" keys onto the runtime "focused" state bucket.
+    if (state === "focus") {
+      state = "focused";
+    }
+
     if (!styleName) return;
 
     const camelCaseKey = toCamelCase(styleName);

package/configurationUtils/modalBlocksParser.ts

@@ -25,6 +25,10 @@ export type ModalBlocksConfig = {
     buttonsContainer: Record<string, any>;
     button1: Record<string, any>;
     button2: Record<string, any>;
+    /** Studio item.checkbox_asset / item.checked_checkbox_asset */
+    checkbox?: Record<string, any>;
+    /** Studio reorder/remove icons for Edit Order rows */
+    actionButtons?: Record<string, any>;
   };
   nowPlayingItem?: {
     background: Record<string, any>;
@@ -37,6 +41,8 @@ export type ModalBlocksConfig = {
     buttonsContainer: Record<string, any>;
     button1: Record<string, any>;
     button2: Record<string, any>;
+    checkbox?: Record<string, any>;
+    actionButtons?: Record<string, any>;
   };
   button: {
     background: Record<string, any>;
@@ -75,6 +81,8 @@ export const parseModalBlocksConfiguration = (
       buttonsContainer: {},
       button1: {},
       button2: {},
+      checkbox: {},
+      actionButtons: {},
     },
     nowPlayingItem: {
       background: {},
@@ -87,6 +95,8 @@ export const parseModalBlocksConfiguration = (
       buttonsContainer: {},
       button1: {},
       button2: {},
+      checkbox: {},
+      actionButtons: {},
     },
     button: {
       background: {},
@@ -152,8 +162,12 @@ export const parseModalBlocksConfiguration = (
     "now_playing_container",
     "now_playing_asset",
     "now_playing_label",
+    // Underscored form (QB convention) and Studio/manifest-generator form
+    // without the underscore before the digit (text_label1).
     "text_label_1",
     "text_label_2",
+    "text_label1",
+    "text_label2",
     "buttons_container",
     "button_1",
     "button_2",
@@ -167,6 +181,8 @@ export const parseModalBlocksConfiguration = (
     "now_playing_label",
     "text_label_1",
     "text_label_2",
+    "text_label1",
+    "text_label2",
     "buttons_container",
     "button_1",
     "button_2",
@@ -174,5 +190,107 @@ export const parseModalBlocksConfiguration = (
 
   parseBlock("button", ["background", "title", "icons", "leading_icon"]);
 
+  // Playlist-experience Studio keys live in this shared parser because modal
+  // blocks are themed by themePluginId. Gate them so other plugins are not
+  // affected by playlist-only asset names.
+  const isPlaylistExperience =
+    normalizedComponentName === "playlist_experience";
+
+  // Studio uploads Create New icon as button.create_new_playlist_asset (not
+  // button.leading_icon.asset). Map it onto leadingIcon so AudioPlayerButton
+  // can override the hardcoded action-type asset.
+  const createNewPlaylistAsset = isPlaylistExperience
+    ? configuration["button.create_new_playlist_asset"] ||
+      configuration[
+        `${normalizedComponentName}_button_create_new_playlist_asset`
+      ]
+    : undefined;
+
+  if (createNewPlaylistAsset) {
+    if (!result.button.leadingIcon.default) {
+      result.button.leadingIcon.default = {};
+    }
+
+    result.button.leadingIcon.default.asset = createNewPlaylistAsset;
+  }
+
+  // Studio checkbox assets are top-level item.* keys (not a parseBlock
+  // sub-component). Map onto item.checkbox so multiSelect can render them.
+  const checkboxAsset =
+    configuration["item.checkbox_asset"] ||
+    configuration[`${normalizedComponentName}_item_checkbox_asset`];
+
+  const checkedCheckboxAsset =
+    configuration["item.checked_checkbox_asset"] ||
+    configuration[`${normalizedComponentName}_item_checked_checkbox_asset`];
+
+  if (checkboxAsset || checkedCheckboxAsset) {
+    if (!result.item.checkbox.default) {
+      result.item.checkbox.default = {};
+    }
+
+    if (checkboxAsset) {
+      result.item.checkbox.default.asset = checkboxAsset;
+    }
+
+    if (checkedCheckboxAsset) {
+      result.item.checkbox.default.checkedAsset = checkedCheckboxAsset;
+    }
+  }
+
+  // Edit Order row icons: prefer reorder_playlist_item.*, then flavor1, then
+  // flavor2 playlist_experience_assets_* (playlist-experience theme only).
+  const removeAsset = isPlaylistExperience
+    ? configuration["reorder_playlist_item.remove_from_playlist_asset"] ||
+      configuration[
+        `${normalizedComponentName}_reorder_playlist_item_remove_from_playlist_asset`
+      ] ||
+      configuration[
+        "playlist_experience_assets_flavor1.remove_from_playlist_asset"
+      ] ||
+      configuration[
+        `${normalizedComponentName}_assets_flavor1_remove_from_playlist_asset`
+      ] ||
+      configuration[
+        "playlist_experience_assets_flavor2.remove_from_playlist_asset"
+      ] ||
+      configuration[
+        `${normalizedComponentName}_assets_flavor2_remove_from_playlist_asset`
+      ]
+    : undefined;
+
+  const dragAsset = isPlaylistExperience
+    ? configuration["reorder_playlist_item.reorder_handle_asset"] ||
+      configuration[
+        `${normalizedComponentName}_reorder_playlist_item_reorder_handle_asset`
+      ] ||
+      configuration[
+        "playlist_experience_assets_flavor1.reorder_handle_asset"
+      ] ||
+      configuration[
+        `${normalizedComponentName}_assets_flavor1_reorder_handle_asset`
+      ] ||
+      configuration[
+        "playlist_experience_assets_flavor2.reorder_handle_asset"
+      ] ||
+      configuration[
+        `${normalizedComponentName}_assets_flavor2_reorder_handle_asset`
+      ]
+    : undefined;
+
+  if (removeAsset || dragAsset) {
+    if (!result.item.actionButtons.default) {
+      result.item.actionButtons.default = {};
+    }
+
+    if (removeAsset) {
+      result.item.actionButtons.default.removeAsset = removeAsset;
+    }
+
+    if (dragAsset) {
+      result.item.actionButtons.default.dragAsset = dragAsset;
+    }
+  }
+
   return result;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-rc.80",
+  "version": "16.0.0-rc.82",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.80",
+    "@applicaster/applicaster-types": "16.0.0-rc.82",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/reactHooks/navigation/__tests__/index.test.tsx

@@ -7,6 +7,7 @@ import configureMockStore from "redux-mock-store";
 import { NavigationContext } from "@applicaster/zapp-react-native-ui-components/Contexts/NavigationContext";
 import { ROUTE_TYPES } from "@applicaster/zapp-react-native-utils/navigationUtils/routeTypes";
 import { ScreenDataContext } from "@applicaster/zapp-react-native-ui-components/Contexts/ScreenDataContext";
+import { modalStore } from "@applicaster/zapp-react-native-utils/modalState";
 
 const plugins = [];
 
@@ -156,6 +157,20 @@ const videoModalWrapper = ({ children }) => (
   </Provider>
 );
 
+const modalEntry = { id: "modal-entry-1", type: { value: "video" } };
+
+const modalPathname = `${ROUTE_TYPES.MODAL}/${rivers["river-general"].id}`;
+
+const modalWrapper = ({ children }) => (
+  <Provider store={store}>
+    <NavigationContext.Provider value={mainStackNavigator}>
+      <PathnameContext.Provider value={modalPathname}>
+        {children}
+      </PathnameContext.Provider>
+    </NavigationContext.Provider>
+  </Provider>
+);
+
 const hookModalWrapper = ({ children }) => (
   <Provider store={store}>
     <NavigationContext.Provider value={hookModalNavigator}>
@@ -188,6 +203,39 @@ describe("navigation", () => {
       });
     });
 
+    describe("Modal components", () => {
+      beforeEach(() => {
+        modalStore.getState().openModal({
+          item: rivers["river-general"] as any,
+          props: { entry: modalEntry },
+        });
+      });
+
+      afterEach(() => {
+        modalStore.getState().dismissModal();
+      });
+
+      it("should return a correct pathname", () => {
+        const { result } = renderHook(() => useRoute(), {
+          wrapper: modalWrapper,
+        });
+
+        expect(result.current.pathname).toEqual(modalPathname);
+      });
+
+      it("should return correct screenData information", () => {
+        const { result } = renderHook(() => useRoute(), {
+          wrapper: modalWrapper,
+        });
+
+        expect(result.current.screenData.id).toEqual(modalEntry.id);
+
+        expect(result.current.screenData.targetScreen.id).toEqual(
+          rivers["river-general"].id
+        );
+      });
+    });
+
     describe("Hook modal components", () => {
       it("should return a correct pathname", () => {
         const { result } = renderHook(() => useRoute(), {

package/reactHooks/navigation/__tests__/usePresentScreen.test.ts

@@ -0,0 +1,154 @@
+import { modalStore } from "../../../modalState";
+import { isWeb } from "../../../reactUtils";
+import { presentScreen } from "../usePresentScreen";
+
+jest.mock("../../../reactUtils", () => ({
+  ...jest.requireActual("../../../reactUtils"),
+  isWeb: jest.fn(() => false),
+}));
+
+const river = { id: "river-parent-lock", type: "parent_lock" } as any;
+
+const rivers = { "river-parent-lock": river };
+
+const contentTypes = { parent_lock: { screen_id: "river-parent-lock" } };
+
+const present = (args = {}) =>
+  presentScreen({ typeMapping: "parent_lock", rivers, contentTypes, ...args });
+
+const modalState = () => modalStore.getState().modalState;
+
+const screenCallback = () => modalState().props?.resultCallback as hookCallback;
+
+describe("presentScreen", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (isWeb as jest.Mock).mockReturnValue(false);
+    modalStore.getState().dismissModal();
+  });
+
+  it("opens a modal with the river resolved from typeMapping", () => {
+    void present();
+
+    expect(modalState().visible).toBe(true);
+    expect(modalState().screen).toBe(river);
+  });
+
+  it("resolves with success when the presented screen reports success", async () => {
+    const result = present();
+
+    screenCallback()({ success: true, payload: { verified: true } });
+
+    await expect(result).resolves.toMatchObject({
+      success: true,
+      cancelled: false,
+      payload: { verified: true },
+    });
+  });
+
+  it("dismisses the modal once the presented screen reports a result", async () => {
+    const result = present();
+
+    screenCallback()({ success: true, payload: {} });
+    await result;
+
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("resolves as cancelled when the modal is dismissed without a result", async () => {
+    const result = present();
+
+    // What the hardware back button does: RN Modal's onRequestClose resets modal state.
+    modalStore.getState().dismissModal();
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("resolves as cancelled when the presented screen reports cancellation", async () => {
+    const result = present();
+
+    screenCallback()({ success: false, payload: {}, cancelled: true });
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("resolves as cancelled when another modal replaces the presented screen", async () => {
+    const result = present();
+
+    modalStore.getState().openModal({ item: { id: "other-modal" } as any });
+
+    await expect(result).resolves.toMatchObject({ cancelled: true });
+  });
+
+  it("leaves the modal that replaced the presented screen open", async () => {
+    const result = present();
+    const other = { id: "other-modal" } as any;
+
+    modalStore.getState().openModal({ item: other });
+    await result;
+
+    expect(modalState().screen).toBe(other);
+    expect(modalState().visible).toBe(true);
+  });
+
+  it("ignores a result reported after the modal was already cancelled", async () => {
+    const result = present();
+    const callback = screenCallback();
+
+    modalStore.getState().dismissModal();
+    callback({ success: true, payload: {} });
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("hands the entry to the ModalProvider so it reaches ScreenDataContext", () => {
+    const entry = { id: "entry-1", type: { value: "video" } } as any;
+
+    void present({ entry });
+
+    expect(modalState().props?.entry).toBe(entry);
+  });
+
+  it("omits the entry when the screen is presented without one", () => {
+    void present();
+
+    expect(modalState().props).not.toHaveProperty("entry");
+  });
+
+  it("fails without opening a modal when typeMapping has no content type", async () => {
+    const result = await present({ typeMapping: "unmapped" });
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("fails without opening a modal when the content type resolves to a missing river", async () => {
+    const result = await present({
+      contentTypes: { parent_lock: { screen_id: "gone" } },
+    });
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("fails without opening a modal on web, where no modal host exists", async () => {
+    (isWeb as jest.Mock).mockReturnValue(true);
+
+    const result = await present();
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+});

package/reactHooks/navigation/index.ts

@@ -22,6 +22,8 @@ import { useLayoutVersion } from "../layout";
 
 export { useNavigation } from "./useNavigation";
 
+export { usePresentScreen, presentScreen } from "./usePresentScreen";
+
 export { useRoute } from "./useRoute";
 
 export { usePathname } from "./usePathname";

package/reactHooks/navigation/usePresentScreen.ts

@@ -0,0 +1,157 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { useCallback } from "react";
+
+import { useContentTypes } from "@applicaster/zapp-react-native-redux/hooks";
+
+import { modalStore } from "../../modalState";
+import { isWeb } from "../../reactUtils";
+import { createLogger } from "../../logger";
+import { useRivers } from "../state";
+
+const { log_error, log_info } = createLogger({
+  subsystem: "usePresentScreen",
+  category: "General",
+});
+
+export interface PresentScreenArgs {
+  /** The screen type to present (from content types mapping) */
+  typeMapping: string;
+
+  /** Entry to present the screen with. Omit to present the screen on its own. */
+  entry?: ZappEntry;
+}
+
+export interface PresentScreenResult {
+  /** The presented screen completed successfully */
+  success: boolean;
+
+  /** The presented screen was dismissed without completing (e.g. the back button) */
+  cancelled: boolean;
+
+  /** Set when the screen could not be presented at all */
+  error?: string;
+
+  /** Whatever the presented screen reported back */
+  payload?: unknown;
+}
+
+export type PresentScreenFn = (
+  args: PresentScreenArgs
+) => Promise<PresentScreenResult>;
+
+interface Dependencies {
+  rivers: Record<string, ZappRiver>;
+  contentTypes: ZappContentTypes;
+}
+
+const failure = (error: string): Promise<PresentScreenResult> => {
+  log_error(`presentScreen: ${error}`);
+
+  return Promise.resolve({ success: false, cancelled: false, error });
+};
+
+/**
+ * Presents a screen as a modal and resolves once that screen reports a result
+ * or is dismissed.
+ *
+ * The screen is rendered by the ModalProvider through the regular ScreenResolver,
+ * so it receives the `resultCallback` we pass here as its `callback` prop — the
+ * same channel hook screens already use to report success and cancellation.
+ */
+export const presentScreen = ({
+  typeMapping,
+  entry,
+  rivers,
+  contentTypes,
+}: PresentScreenArgs & Dependencies): Promise<PresentScreenResult> => {
+  if (!typeMapping) {
+    return failure("typeMapping option is missing");
+  }
+
+  // The web ModalProvider renders nothing, so no result could ever arrive and
+  // awaiting one would stall the caller indefinitely.
+  if (isWeb()) {
+    return failure("screens can not be presented as modals on web");
+  }
+
+  const screenId = contentTypes?.[typeMapping]?.screen_id;
+
+  if (!screenId) {
+    return failure(`can not resolve screen type mapping: ${typeMapping}`);
+  }
+
+  const river = rivers?.[screenId];
+
+  if (!river) {
+    return failure(`can not resolve river for screen id: ${screenId}`);
+  }
+
+  return new Promise<PresentScreenResult>((resolve) => {
+    let settled = false;
+    let unsubscribe: () => void = () => {};
+
+    const settle = (result: PresentScreenResult) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      unsubscribe();
+      resolve(result);
+    };
+
+    const resultCallback = ({
+      success,
+      cancelled,
+      payload,
+    }: hookCallbackArgs) =>
+      settle({ success: !!success, cancelled: !!cancelled, payload });
+
+    const props: Record<string, unknown> = { resultCallback };
+
+    if (entry) {
+      // The ModalProvider turns this into the screen's ScreenDataContext and
+      // screenData, so the presented screen reads the entry exactly as it
+      // would when navigated to.
+      props.entry = entry;
+    }
+
+    log_info(
+      `presentScreen: presenting screen type: ${typeMapping}${
+        entry ? ` with entry id: ${entry.id}` : ""
+      }`
+    );
+
+    modalStore.getState().openModal({ item: river, props });
+
+    // Covers every dismissal we do not initiate ourselves: the hardware back
+    // button (via the Modal's onRequestClose), a swipe dismiss, another modal
+    // taking our slot, or dismissModal() called from anywhere else.
+    unsubscribe = modalStore.subscribe(({ modalState }) => {
+      if (!modalState.visible || modalState.screen !== river) {
+        settle({ success: false, cancelled: true });
+      }
+    });
+  }).then((result) => {
+    // Only take down our own modal — by now something else may already own the slot.
+    if (modalStore.getState().modalState.screen === river) {
+      modalStore.getState().dismissModal();
+    }
+
+    return result;
+  });
+};
+
+/**
+ * @returns a function presenting a screen as a modal, resolving with its result.
+ */
+export const usePresentScreen = (): PresentScreenFn => {
+  const rivers = useRivers();
+  const contentTypes = useContentTypes();
+
+  return useCallback(
+    (args: PresentScreenArgs) =>
+      presentScreen({ ...args, rivers, contentTypes }),
+    [rivers, contentTypes]
+  );
+};

package/reactHooks/navigation/useRoute.ts

@@ -80,7 +80,20 @@ export const useRoute = (
   // if path is hook grab screenData from screenData
 
   if (isModalPathname(pathname)) {
-    const screenData = modalScreenData ?? ({} as ZappEntry);
+    if (!modalScreenData) {
+      return { screenData: {} as ZappEntry, pathname };
+    }
+
+    // Mirror the pushed-screen shape ({ ...entry, targetScreen }) so a screen
+    // presented as a modal reads its entry the same way it would when
+    // navigated to, instead of only seeing the bare river.
+    const screenData = legacyScreenData(
+      {
+        screen: modalScreenData,
+        entry: modalState.props?.entry as NavigatorEntry,
+      },
+      plugins
+    );
 
     return { screenData, pathname };
   }