@applicaster/zapp-react-native-ui-components 16.0.0-rc.113 → 16.0.0-rc.114

package/Components/AudioPlayer/tv/Layout.tsx

@@ -7,7 +7,7 @@ import { Artwork } from "./Artwork";
 import { directionStyles } from "./helpers";
 
 type Props = {
-  artwork: string;
+  artwork: Option<string>;
   config: {
     titleColor: string;
     summaryColor: string;
@@ -152,7 +152,7 @@ export function AudioPlayerTVLayout({
         resizeMode="cover"
       >
         <View style={[mainContainerStyles, backgroundOverlayStyles]}>
-          <Artwork srcImage={artwork} config={config} />
+          {artwork ? <Artwork srcImage={artwork} config={config} /> : null}
           <View style={textContainerStyles}>{children}</View>
         </View>
       </ImageBackground>
@@ -161,7 +161,7 @@ export function AudioPlayerTVLayout({
 
   return (
     <View style={mainContainerStyles}>
-      <Artwork srcImage={artwork} config={config} />
+      {artwork ? <Artwork srcImage={artwork} config={config} /> : null}
       <View style={textContainerStyles}>{children}</View>
     </View>
   );

package/Components/ModalComponent/AudioPlayer/utils/__tests__/mergeStyles.test.ts

@@ -287,6 +287,46 @@ describe("mergeButtonConfiguration background", () => {
     expect(merged.title.androidLetterSpacing).toBe(-0.5);
     expect(merged.title.textTransform).toBe("uppercase");
   });
+
+  it("uses the family string inside a font-selector object and ignores {}", () => {
+    const fromObject = mergeButtonConfiguration(buttonBase as any, {
+      title: {
+        default: { fontFamily: { fontFamily: "GreycliffCF-Bold" } },
+      },
+    });
+
+    expect(fromObject.title.iosFontFamily).toBe("GreycliffCF-Bold");
+    expect(fromObject.title.androidFontFamily).toBe("GreycliffCF-Bold");
+
+    const fromEmpty = mergeButtonConfiguration(buttonBase as any, {
+      title: {
+        default: { fontFamily: {} },
+      },
+    });
+
+    expect(fromEmpty.title.iosFontFamily).toBe(buttonBase.title.iosFontFamily);
+
+    expect(fromEmpty.title.androidFontFamily).toBe(
+      buttonBase.title.androidFontFamily
+    );
+  });
+
+  it("maps inactive color, gutter, and focused and inactive font colors", () => {
+    const merged = mergeButtonConfiguration(buttonBase as any, {
+      background: {
+        default: { inactiveColor: "#999999", horizontalGutter: 6 },
+      },
+      title: {
+        default: { inactiveFontColor: "#111111" },
+        focused: { fontColor: "#222222" },
+      },
+    });
+
+    expect(merged.background.inactiveColor).toBe("#999999");
+    expect(merged.background.horizontalGutter).toBe(6);
+    expect(merged.title.inactiveFontColor).toBe("#111111");
+    expect(merged.title.focusedFontColor).toBe("#222222");
+  });
 });
 
 describe("mergeHeaderConfiguration section header (Variant 3)", () => {

package/Components/ModalComponent/AudioPlayer/utils/mergeStyles.ts

@@ -381,6 +381,22 @@ export function mergeHeaderConfiguration(
 // Button Merging Helpers
 // ---------------------------------------------------------------------------
 
+function fontFamilyName(value: unknown): string | undefined {
+  if (typeof value === "string" && value.trim()) {
+    return value;
+  }
+
+  if (value && typeof value === "object") {
+    const family = (value as { fontFamily?: unknown }).fontFamily;
+
+    if (typeof family === "string" && family.trim()) {
+      return family;
+    }
+  }
+
+  return undefined;
+}
+
 function mergeButtonBackground(
   base: ButtonBackgroundConfiguration,
   defaultOverride?: Record<string, any>,
@@ -399,6 +415,9 @@ function mergeButtonBackground(
     ...(defaultOverride?.backgroundColor
       ? { defaultColor: defaultOverride.backgroundColor }
       : {}),
+    ...(defaultOverride?.inactiveColor
+      ? { inactiveColor: defaultOverride.inactiveColor }
+      : {}),
     ...(focusedColor != null && focusedColor !== "" ? { focusedColor } : {}),
     ...(defaultOverride?.borderRadius !== undefined
       ? { cornerRadius: defaultOverride.borderRadius }
@@ -415,47 +434,62 @@ function mergeButtonBackground(
     ...(defaultOverride?.paddingLeft !== undefined
       ? { paddingLeft: defaultOverride.paddingLeft }
       : {}),
+    ...(defaultOverride?.horizontalGutter !== undefined
+      ? { horizontalGutter: defaultOverride.horizontalGutter }
+      : {}),
   };
 }
 
 function mergeButtonTitle(
   base: ButtonTitleConfiguration,
-  override?: Record<string, any>
+  override?: Record<string, any>,
+  focusedOverride?: Record<string, any>
 ): ButtonTitleConfiguration {
-  if (!override) return base;
+  if (!override && !focusedOverride) return base;
+
+  const fontFamily = fontFamilyName(override?.fontFamily);
+
+  const focusedFontColor =
+    focusedOverride?.fontColor || override?.focusedFontColor;
+
+  const inactiveFontColor = override?.inactiveFontColor;
 
   return {
     ...base,
-    ...(override.fontColor ? { fontColor: override.fontColor } : {}),
-    ...(override.fontSize !== undefined ? { fontSize: override.fontSize } : {}),
-    ...(override.lineHeight !== undefined
+    ...(override?.fontColor ? { fontColor: override.fontColor } : {}),
+    ...(focusedFontColor ? { focusedFontColor } : {}),
+    ...(inactiveFontColor ? { inactiveFontColor } : {}),
+    ...(override?.fontSize !== undefined
+      ? { fontSize: override.fontSize }
+      : {}),
+    ...(override?.lineHeight !== undefined
       ? { lineHeight: override.lineHeight }
       : {}),
-    ...(override.fontFamily
+    ...(fontFamily
       ? {
-          iosFontFamily: override.fontFamily,
-          androidFontFamily: override.fontFamily,
+          iosFontFamily: fontFamily,
+          androidFontFamily: fontFamily,
         }
       : {}),
-    ...(override.iosFontFamily
+    ...(override?.iosFontFamily
       ? { iosFontFamily: override.iosFontFamily }
       : {}),
-    ...(override.androidFontFamily
+    ...(override?.androidFontFamily
       ? { androidFontFamily: override.androidFontFamily }
       : {}),
-    ...(override.letterSpacing !== undefined
+    ...(override?.letterSpacing !== undefined
       ? {
           iosLetterSpacing: override.letterSpacing,
           androidLetterSpacing: override.letterSpacing,
         }
       : {}),
-    ...(override.iosLetterSpacing !== undefined
+    ...(override?.iosLetterSpacing !== undefined
       ? { iosLetterSpacing: override.iosLetterSpacing }
       : {}),
-    ...(override.androidLetterSpacing !== undefined
+    ...(override?.androidLetterSpacing !== undefined
       ? { androidLetterSpacing: override.androidLetterSpacing }
       : {}),
-    ...(override.textTransform
+    ...(override?.textTransform
       ? { textTransform: override.textTransform }
       : {}),
   };
@@ -511,13 +545,19 @@ export function mergeButtonConfiguration(
   const titleOverride =
     buttonBlock?.title?.default || actionBlock?.title?.default;
 
+  const titleFocused =
+    buttonBlock?.title?.focused ||
+    buttonBlock?.title?.focus ||
+    actionBlock?.title?.focused ||
+    actionBlock?.title?.focus;
+
   const iconsOverride = buttonBlock?.icons || actionBlock?.icons;
   const leadingOverride = buttonBlock?.leadingIcon || actionBlock?.leadingIcon;
 
   return {
     ...base,
     background: mergeButtonBackground(base.background, bgDefault, bgFocused),
-    title: mergeButtonTitle(base.title, titleOverride),
+    title: mergeButtonTitle(base.title, titleOverride, titleFocused),
     icons: mergeButtonIcons(base.icons, iconsOverride, leadingOverride),
   };
 }

package/Components/ModalComponent/BottomSheetModalContent.tsx

@@ -90,6 +90,7 @@ type ModalComponentProps = {
   /** Optional body that replaces the items list (header stays DefaultModalHeader). */
   contentComponent?: React.ComponentType<any>;
   contentComponentProps?: Record<string, any>;
+  themePluginId?: string;
   styleOverrides?: ModalBlocksConfig | Record<string, any>;
   measurementPhase?: boolean;
   /** Copy under Next Up when the queue has no upcoming items. */
@@ -115,6 +116,7 @@ function _BottomSheetModalContent(props: ModalComponentProps) {
     iconPlacement,
     contentComponent: ContentComponent,
     contentComponentProps = {},
+    themePluginId: themePluginIdProp,
     measurementPhase = false,
     emptyMessage,
   } = props;
@@ -139,12 +141,14 @@ function _BottomSheetModalContent(props: ModalComponentProps) {
     role,
     behavior,
     editableCollection,
-    themePluginId,
+    themePluginId: themePluginIdFromSheet,
   } = useBottomSheetContent({
     onPress,
     viewModel,
   });
 
+  const themePluginId = themePluginIdFromSheet || themePluginIdProp;
+
   const plugins = usePlugins();
 
   const plugin = useMemo(

package/Components/ModalComponent/__tests__/showTextInput.test.ts

@@ -92,4 +92,29 @@ describe("showTextInputAction", () => {
     expect(result).toBe(ActionResult.Error);
     expect(actionExecutor.handleAction).not.toHaveBeenCalled();
   });
+
+  it("forwards themePluginId so the sheet can read plugin button styles", async () => {
+    const action = {
+      type: "showTextInput",
+      options: {
+        headerTitle: "Create New Playlist",
+        inputLabel: "Name your playlist",
+        buttonLabel: "Create",
+        themePluginId: "playlist-experience",
+        actions: [{ type: "sendCloudEvent", options: {} }],
+      },
+    };
+
+    await showTextInputAction(action as any);
+
+    expect(actionExecutor.handleAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "openBottomSheet",
+        options: expect.objectContaining({
+          themePluginId: "playlist-experience",
+        }),
+      }),
+      undefined
+    );
+  });
 });

package/Components/ModalComponent/showTextInput.ts

@@ -21,6 +21,7 @@ export async function showTextInputAction(
     validationLabel,
     actions,
     maxLength,
+    themePluginId,
   } = action.options || {};
 
   if (!headerTitle || !buttonLabel || !actions || !actions.length) {
@@ -34,6 +35,7 @@ export async function showTextInputAction(
         header: {
           title: headerTitle,
         },
+        ...(themePluginId ? { themePluginId } : {}),
         content: {
           component: TextInputContent,
           props: {

package/Components/River/ComponentsMap/ComponentsMap.tsx

@@ -118,7 +118,10 @@ function ComponentsMapComponent(props: Props) {
       };
 
       return (
-        <ScreenLoadingMeasurementsListItemWrapper index={index}>
+        <ScreenLoadingMeasurementsListItemWrapper
+          index={index}
+          testID={`component-${item.id}`}
+        >
           <RiverItem {...riverItemProps} />
         </ScreenLoadingMeasurementsListItemWrapper>
       );

package/Components/River/__tests__/__snapshots__/componentsMap.test.js.snap

@@ -213,6 +213,7 @@ exports[`componentsMap renders renders components map correctly 1`] = `
           <View
             onLayout={[Function]}
             style={{}}
+            testID="component-A1"
           >
             <View />
           </View>
@@ -225,6 +226,7 @@ exports[`componentsMap renders renders components map correctly 1`] = `
           <View
             onLayout={[Function]}
             style={{}}
+            testID="component-A2"
           />
         </View>
         <View

package/Decorators/ZappPipesDataConnector/__tests__/screenToolbox.test.ts

@@ -0,0 +1,347 @@
+import { renderHook } from "@testing-library/react-native";
+
+const mockRegister = jest.fn().mockResolvedValue(undefined);
+
+// The X-Ray mock (__mocks__/@applicaster/quick-brick-xray) has no toolbox API: give it one.
+require("@applicaster/quick-brick-xray").registerReactToolbox = mockRegister;
+
+// Required after the toolbox API is in place: loading them can register the player toolbox.
+const {
+  modalStore,
+} = require("@applicaster/zapp-react-native-utils/modalState");
+
+const {
+  setXrayNavigator,
+} = require("@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator");
+
+const {
+  zappHookModalStore,
+} = require("@applicaster/zapp-react-native-ui-components/Contexts/ZappHookModalContext");
+
+const mockStore = {
+  rivers: { home: { name: "Home", type: "general_content" } },
+  plugins: [
+    { identifier: "quick-brick-epg-screen", name: "EPG" },
+    { identifier: "login-plugin", name: "Login" },
+  ],
+};
+
+jest.mock("@applicaster/zapp-react-native-redux/AppStore", () => ({
+  appStore: { get: (key) => mockStore[key] },
+}));
+
+const { useScreenToolboxRecord, getTopPathname } = require("../screenToolbox");
+
+const home = { id: "home", name: "Home", type: "general_content" };
+
+const stack = {
+  "/river/home": { screen: home },
+  "/river/epg": {
+    screen: { id: "epg", name: "Guide", type: "quick-brick-epg-screen" },
+  },
+  "/river/tabs": {
+    screen: { id: "tabs", name: "Tabs", type: "quick-brick-tabs" },
+    nested: { screen: { id: "t1", name: "Tab 1", type: "general_content" } },
+  },
+  "/river/home/hooks/login": {
+    screen: { identifier: "login-plugin", name: "Login" },
+    entry: { payload: { id: "e1", title: "One" } },
+  },
+};
+
+const navigate = (pathname: string, videoModalState = { visible: false }) =>
+  setXrayNavigator({
+    getPathname: () => pathname,
+    getStackForPathname: (route) =>
+      stack[route] ? { route, state: stack[route] } : undefined,
+    videoModalState,
+  } as unknown as QuickBrickAppNavigator);
+
+const mount = (
+  component,
+  index,
+  feed?,
+  parentId?,
+  pathname = "/river/home"
+) => {
+  const hook = renderHook(() =>
+    useScreenToolboxRecord(component, "home", index, parentId, pathname)
+  );
+
+  hook.result.current.feed = feed;
+
+  return hook;
+};
+
+const current = (args = {}) => {
+  // Other toolboxes (player) may register first.
+  const { tools } = mockRegister.mock.calls.find(
+    ([toolbox]) => toolbox.name === "screen"
+  )[0];
+
+  return tools.find((tool) => tool.name === "current").handler(args);
+};
+
+const presentHook = (overrides = {}) =>
+  zappHookModalStore.setState({
+    state: {
+      path: "/hooks/login",
+      screenData: {
+        hookPlugin: { identifier: "login-plugin", name: "Login" },
+        payload: { id: "e1", title: "One" },
+      },
+    } as any,
+    isHooksExecutionInProgress: true,
+    isRunningInBackground: false,
+    ...overrides,
+  });
+
+describe("screenToolbox", () => {
+  // Registers the toolbox; the registration is kept for the whole module, as in the app.
+  beforeAll(() => mount({ id: "init" }, 0).unmount());
+
+  beforeEach(() => navigate("/river/home"));
+
+  afterEach(() => {
+    modalStore.getState().setModalState({ visible: false, screen: null });
+    zappHookModalStore.getState().resetState();
+    zappHookModalStore.getState().setIsHooksExecutionInProgress(false);
+  });
+
+  it("returns the top screen's mounted components in order, with feed and entries", () => {
+    const second = mount({ id: "c2", component_type: "grid" }, 1, {
+      url: "https://feed/2",
+      loading: true,
+    });
+
+    const first = mount({ id: "c1", component_type: "horizontal_list" }, 0, {
+      url: "https://feed/1",
+      loading: false,
+      data: {
+        entry: [
+          { id: "e1", title: "One" },
+          { id: "e2", title: "Two" },
+        ],
+      },
+    });
+
+    const third = mount({ id: "c3", component_type: "grid" }, 2, {
+      url: "https://feed/3",
+      error: new Error("404"),
+    });
+
+    expect(current({ limit: 1 })).toEqual({
+      pathname: "/river/home",
+      screen: {
+        kind: "river",
+        id: "home",
+        name: "Home",
+        type: "general_content",
+      },
+      entry: null,
+      rivers: [
+        {
+          id: "home",
+          name: "Home",
+          type: "general_content",
+          components: [
+            {
+              index: 0,
+              id: "c1",
+              type: "horizontal_list",
+              feed: { url: "https://feed/1", state: "loaded", count: 2 },
+              entries: [{ index: 0, id: "e1", title: "One" }],
+            },
+            {
+              index: 1,
+              id: "c2",
+              type: "grid",
+              feed: { url: "https://feed/2", state: "loading", count: 0 },
+              entries: [],
+            },
+            {
+              index: 2,
+              id: "c3",
+              type: "grid",
+              feed: {
+                url: "https://feed/3",
+                state: "error",
+                error: "404",
+                count: 0,
+              },
+              entries: [],
+            },
+          ],
+        },
+      ],
+      mounted: ["/river/home"],
+    });
+
+    [first, second, third].forEach((hook) => hook.unmount());
+
+    expect(current().rivers).toEqual([]);
+  });
+
+  it("nests a group's children under it", () => {
+    const group = mount({ id: "g", component_type: "group" }, 1);
+
+    const child = mount(
+      { id: "g0", component_type: "hero" },
+      0,
+      undefined,
+      "g"
+    );
+
+    const row = mount({ id: "r", component_type: "grid" }, 0);
+
+    expect(
+      current().rivers[0].components.map(({ id, children }) => ({
+        id,
+        children: children?.map((item) => item.id),
+      }))
+    ).toEqual([
+      { id: "r", children: undefined },
+      { id: "g", children: ["g0"] },
+    ]);
+
+    [group, child, row].forEach((hook) => hook.unmount());
+  });
+
+  it("reads another mounted screen by pathname", () => {
+    const other = mount({ id: "c" }, 0, undefined, undefined, "/river/epg");
+
+    expect(current({ pathname: "/river/epg" }).rivers[0].components).toEqual([
+      expect.objectContaining({ id: "c" }),
+    ]);
+
+    expect(current().mounted).toEqual(["/river/epg"]);
+
+    other.unmount();
+  });
+
+  it("names the plugin that renders a screen plugin", () => {
+    navigate("/river/epg");
+
+    expect(current().screen).toEqual({
+      kind: "plugin",
+      id: "epg",
+      name: "Guide",
+      type: "quick-brick-epg-screen",
+      plugin: { identifier: "quick-brick-epg-screen", name: "EPG" },
+    });
+  });
+
+  it("reports the nested tab screen", () => {
+    navigate("/river/tabs");
+
+    expect(current().nested).toEqual({
+      id: "t1",
+      name: "Tab 1",
+      type: "general_content",
+    });
+  });
+
+  it("unwraps the entry of a hook screen on the stack", () => {
+    navigate("/river/home/hooks/login");
+
+    expect(current()).toMatchObject({
+      screen: { kind: "hook", plugin: { identifier: "login-plugin" } },
+      entry: { id: "e1", title: "One" },
+    });
+  });
+
+  it("says when there is no screen yet", () => {
+    navigate("/");
+
+    expect(current().screen).toEqual({ kind: "none" });
+  });
+
+  it("reads a modal's screen from the modal store, its pathname as ModalProvider builds it", () => {
+    modalStore.getState().openModal({ item: home, props: { screenId: "m1" } });
+
+    expect(current()).toMatchObject({
+      pathname: "modal/m1",
+      screen: { kind: "river", id: "home" },
+    });
+  });
+
+  it("describes a modal hook by its plugin", () => {
+    modalStore.getState().openModal({
+      item: {
+        hookPlugin: { identifier: "login-plugin", name: "Login" },
+        payload: { id: "e1", title: "One" },
+      },
+      props: { screenType: "hooks" },
+    } as any);
+
+    expect(current()).toMatchObject({
+      screen: {
+        kind: "hook",
+        plugin: { identifier: "login-plugin", name: "Login" },
+      },
+      entry: { id: "e1", title: "One" },
+    });
+  });
+
+  it("describes a bottom sheet", () => {
+    modalStore.getState().openModal({
+      item: { modalBottomSheetContentProps: {} },
+    } as any);
+
+    expect(current().screen).toEqual({ kind: "bottomSheet" });
+  });
+
+  it("puts a modal over the video modal, and the video modal over the stack unless docked", () => {
+    const item = { id: "v1", title: "Video" };
+
+    navigate("/river/home", {
+      visible: true,
+      mode: "MAXIMIZED",
+      item,
+    } as any);
+
+    expect(current()).toMatchObject({
+      pathname: "video-modal/v1",
+      screen: { kind: "player" },
+      entry: { id: "v1", title: "Video" },
+    });
+
+    modalStore.getState().openModal({ item: home });
+
+    expect(getTopPathname()).toBe("modal/home");
+
+    modalStore.getState().setModalState({ visible: false, screen: null });
+
+    navigate("/river/home", {
+      visible: true,
+      mode: "MINIMIZED",
+      item,
+    } as any);
+
+    expect(getTopPathname()).toBe("/river/home");
+  });
+
+  it("puts a presented hook screen on top, not one running in the background", () => {
+    presentHook();
+
+    expect(current()).toMatchObject({
+      pathname: "hooks-modal/Login",
+      screen: {
+        kind: "hook",
+        name: "Login",
+        plugin: { identifier: "login-plugin" },
+      },
+      entry: { id: "e1", title: "One" },
+    });
+
+    presentHook({ isRunningInBackground: true });
+
+    expect(getTopPathname()).toBe("/river/home");
+  });
+
+  it("describes nothing for a modal pathname that is no longer presented", () => {
+    expect(current({ pathname: "modal/gone" }).screen).toEqual({
+      kind: "none",
+    });
+  });
+});

package/Decorators/ZappPipesDataConnector/__tests__/screenToolboxUnavailable.test.ts

@@ -0,0 +1,53 @@
+import { act, renderHook } from "@testing-library/react-native";
+
+// Fails the screen toolbox as a build without the X-Ray bridge does. Others (player, loaded with
+// the toolbox's imports) register, or the helper would never let the screen toolbox try.
+const mockRegister = jest.fn((toolbox) =>
+  toolbox.name === "screen"
+    ? Promise.reject(new Error("no bridge"))
+    : Promise.resolve()
+);
+
+// The X-Ray mock (__mocks__/@applicaster/quick-brick-xray) has no toolbox API: give it one.
+require("@applicaster/quick-brick-xray").registerReactToolbox = mockRegister;
+
+jest.mock("@applicaster/zapp-react-native-redux/AppStore", () => ({
+  appStore: { get: () => undefined },
+}));
+
+const { useScreenToolboxRecord } = require("../screenToolbox");
+
+const mount = (id: string) =>
+  renderHook(() =>
+    useScreenToolboxRecord({ id }, "home", 0, undefined, "/river/home")
+  );
+
+const mounted = () => {
+  // Other toolboxes (player) may register first.
+  const { tools } = mockRegister.mock.calls.find(
+    ([toolbox]) => toolbox.name === "screen"
+  )[0];
+
+  return tools
+    .find((tool) => tool.name === "current")
+    .handler({ pathname: "/river/home" }).mounted;
+};
+
+describe("screenToolbox without the X-Ray bridge", () => {
+  it("drops its records and stops recording", async () => {
+    mount("c1");
+
+    // Let the failed registration settle.
+    await act(async () => {});
+
+    expect(mounted()).toEqual([]);
+
+    mount("c2");
+
+    expect(mounted()).toEqual([]);
+
+    expect(
+      mockRegister.mock.calls.filter(([toolbox]) => toolbox.name === "screen")
+    ).toHaveLength(1);
+  });
+});

package/Decorators/ZappPipesDataConnector/index.tsx

@@ -5,7 +5,9 @@ import { useRoute } from "@applicaster/zapp-react-native-utils/reactHooks/naviga
 import { usePlugins } from "@applicaster/zapp-react-native-redux/hooks";
 import { ZappPipesSearchContext } from "@applicaster/zapp-react-native-ui-components/Contexts";
 import { useScreenContext } from "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext";
+import { useUIComponentContext } from "@applicaster/zapp-react-native-ui-components/Contexts/UIComponentContext";
 import { ResolverSelector } from "./ResolverSelector";
+import { useScreenToolboxRecord } from "./screenToolbox";
 import { ComponentDataSourceContext } from "./types";
 
 type Props = {
@@ -22,7 +24,7 @@ export function zappPipesDataConnector(
   Component: React.FC<any> | React.ComponentClass<any>
 ) {
   return function WrappedWithZappPipesData(props: Props) {
-    const { screenData } = useRoute();
+    const { screenData, pathname } = useRoute();
     const plugins = usePlugins();
     const screenContextData = useScreenContext();
 
@@ -53,6 +55,16 @@ export function zappPipesDataConnector(
 
     const [searchContext] = ZappPipesSearchContext.useZappPipesContext();
 
+    const parent = useUIComponentContext() as { id?: string } | null;
+
+    const toolboxRecord = useScreenToolboxRecord(
+      component,
+      riverId,
+      componentIndex,
+      parent?.id,
+      pathname
+    );
+
     // Prepare context for resolvers
     const resolverProps: ComponentDataSourceContext = {
       component,
@@ -71,9 +83,12 @@ export function zappPipesDataConnector(
 
     return (
       <ResolverSelector {...resolverProps}>
-        {(zappPipesDataProps) => (
-          <Component {...props} {...zappPipesDataProps} />
-        )}
+        {(zappPipesDataProps) => {
+          // A plain field on the toolbox record, read only when the agent asks: no render.
+          toolboxRecord.feed = zappPipesDataProps.zappPipesData;
+
+          return <Component {...props} {...zappPipesDataProps} />;
+        }}
       </ResolverSelector>
     );
   };

package/Decorators/ZappPipesDataConnector/screenToolbox.ts

@@ -0,0 +1,384 @@
+import { useEffect, useMemo } from "react";
+import { Platform } from "react-native";
+import * as R from "ramda";
+import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
+import {
+  registerXrayToolbox,
+  XrayToolSpec,
+} from "@applicaster/zapp-react-native-utils/logger/xrayToolbox";
+import { modalStore } from "@applicaster/zapp-react-native-utils/modalState";
+import { ROUTE_TYPES } from "@applicaster/zapp-react-native-utils/navigationUtils/routeTypes";
+import { getXrayNavigator } from "@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator";
+import { isTV } from "@applicaster/zapp-react-native-utils/reactUtils";
+import { zappHookModalStore } from "@applicaster/zapp-react-native-ui-components/Contexts/ZappHookModalContext";
+
+import { ZappPipesData } from "./types";
+
+/**
+ * X-Ray `screen.*` toolbox: what the current screen shows — its river components in order, the
+ * feed each one loaded and the entries it displays. Every river component, on every platform,
+ * goes through the zappPipes decorator, which writes a record here on mount and drops it on
+ * unmount: a plain Set, nothing subscribes to it, so it never renders anything. Records are
+ * dropped for good once X-Ray turns out to have no toolbox bridge (release builds).
+ *
+ * Screens that are not rivers (screen plugins, hooks, the player) report what renders them,
+ * read from navigation and the modal stores; a plugin with state of its own registers its own
+ * toolbox, as the player does.
+ *
+ * Mounted is not visible (lists are virtualised): which rows and cells are on screen comes from
+ * the native `ui.inspect`. River rows carry testID `component-<componentId>` (mobile, tvOS,
+ * Android TV) and cells carry their entry id in their testID.
+ */
+
+type ComponentRecord = {
+  component: ZappUIComponent;
+  riverId: string;
+  index?: number;
+  parentId?: string;
+  pathname: string;
+  /** Written on each render: the data the component was given, after item filter and limit. */
+  feed?: ZappPipesData;
+};
+
+/** What a route shows; `screenType` is how ScreenResolver renders it. */
+type RouteState = {
+  screenType?: string;
+  screen?: any;
+  entry?: Partial<ZappEntry>;
+  nested?: { screen?: ZappRiver };
+};
+
+/** A screen presented over the navigation stack. `covers` is false when it is out of the way. */
+type Layer = RouteState & { pathname: string; covers: boolean };
+
+const records = new Set<ComponentRecord>();
+
+/** Set once registration failed: X-Ray has no toolbox bridge, so nothing will ever read records. */
+let unavailable = false;
+
+const DEFAULT_ENTRIES_LIMIT = 10;
+
+const toLimit = (value: unknown) =>
+  typeof value === "number" && value >= 0 ? value : DEFAULT_ENTRIES_LIMIT;
+
+/** The hooks modal, with the pathname ZappHooksModal gives it; hidden while it runs in the background. */
+const hooksModalLayer = (): Layer | undefined => {
+  const { state, isHooksExecutionInProgress, isRunningInBackground } =
+    zappHookModalStore.getState();
+
+  if (!isHooksExecutionInProgress || !state.path) return undefined;
+
+  const hookPlugin = state.screenData?.hookPlugin;
+
+  return {
+    pathname: `${ROUTE_TYPES.HOOKS_MODAL}/${hookPlugin ? hookPlugin.name : ""}`,
+    covers:
+      !isRunningInBackground && hookPlugin?.module?.presentFullScreen !== false,
+    screenType: "hooks",
+    screen: hookPlugin,
+    entry: state.screenData?.payload as ZappEntry,
+  };
+};
+
+/** The modal screen or bottom sheet, with the pathname and props ModalProvider gives it. */
+const modalLayer = (): Layer | undefined => {
+  const { visible, screen, props } = modalStore.getState().modalState;
+
+  if (!visible || !screen) return undefined;
+
+  const { screenId, screenType, entry, screenData } = {
+    screenId: screen.id,
+    screenType: "river",
+    ...props,
+  } as Record<string, any>;
+
+  // A modal hook (and the ad interstitial) presents a { hookPlugin, payload } wrapper.
+  const isHook = screenType === "hooks";
+
+  return {
+    pathname: `${ROUTE_TYPES.MODAL}/${screenId}`,
+    covers: true,
+    screenType,
+    screen: isHook ? (screen.hookPlugin ?? screenData?.hookPlugin) : screen,
+    entry: isHook ? screen.payload : entry,
+  };
+};
+
+const videoModalLayer = (): Layer | undefined => {
+  const videoModal = getXrayNavigator()?.videoModalState;
+
+  if (!videoModal?.visible) return undefined;
+
+  return {
+    pathname: `${ROUTE_TYPES.VIDEO_MODAL}/${videoModal.item?.id}`,
+    covers: videoModal.mode !== "MINIMIZED",
+    screenType: "playable",
+    entry: videoModal.item,
+  };
+};
+
+/**
+ * Topmost first: the hooks modal and modals are native RN Modals, drawn over the video modal.
+ * Only layers this platform renders: the mobile layout renders the hooks and video modals, and
+ * ModalProvider renders nothing on web.
+ */
+const presentedLayers = () => {
+  const web = Platform.OS === "web";
+  const mobile = !web && !isTV();
+
+  return [
+    mobile && hooksModalLayer(),
+    !web && modalLayer(),
+    mobile && videoModalLayer(),
+  ].filter((layer): layer is Layer => Boolean(layer));
+};
+
+/** The pathname of what is on top: a covering presented layer, else the stack top. */
+export const getTopPathname = (): string | undefined =>
+  presentedLayers().find((layer) => layer.covers)?.pathname ??
+  getXrayNavigator()?.getPathname();
+
+/** What the route at `pathname` shows. Presented layers are not on the stack: their stores hold them. */
+const routeState = (pathname: string): RouteState => {
+  const layer = presentedLayers().find((item) => item.pathname === pathname);
+
+  if (layer) return layer;
+
+  // Not presented any more (a stale modal pathname): nothing to describe.
+  if (!pathname.startsWith("/")) return {};
+
+  const state = getXrayNavigator()?.getStackForPathname(pathname)?.state;
+
+  // A stack route ends in <screenType>/<screenId>.
+  const screenType = pathname.split("/").slice(-2)[0];
+
+  return {
+    screenType,
+    ...state,
+    // A hook screen's entry is the { payload } wrapper it was pushed with.
+    entry:
+      screenType === "hooks"
+        ? ((state?.entry as any)?.payload ?? state?.entry)
+        : state?.entry,
+  };
+};
+
+/** Screen types ScreenResolver renders itself rather than through a screen plugin. */
+const BUILT_IN_KINDS = {
+  playable: "player",
+  link: "link",
+  favorites: "favorites",
+};
+
+/**
+ * What renders the screen, as ScreenResolver picks it: a river of components, a built-in screen,
+ * a hook plugin, or a screen plugin (a river whose type is a plugin identifier, or a route whose
+ * screen type is one).
+ */
+const describeKind = ({
+  screenType,
+  screen,
+}: RouteState): { kind: string; identifier?: string } => {
+  if (!screenType) return { kind: "none" };
+
+  if (screen?.modalBottomSheetContentProps) return { kind: "bottomSheet" };
+
+  if (screenType === "hooks") {
+    return { kind: "hook", identifier: screen?.identifier };
+  }
+
+  if (BUILT_IN_KINDS[screenType]) return { kind: BUILT_IN_KINDS[screenType] };
+
+  if (screenType !== "river") return { kind: "plugin", identifier: screenType };
+
+  return screen?.type === "general_content"
+    ? { kind: "river" }
+    : { kind: "plugin", identifier: screen?.type };
+};
+
+const describePlugin = (identifier?: string) => {
+  if (!identifier) return null;
+
+  const plugins = (appStore.get("plugins") ?? []) as QuickBrickPlugin[];
+
+  return {
+    identifier,
+    name: plugins.find((plugin) => plugin.identifier === identifier)?.name,
+  };
+};
+
+const describeFeed = (feed?: ZappPipesData) => {
+  if (!feed?.url) return null;
+
+  const error = feed.error as { message?: string } | undefined;
+
+  return {
+    url: feed.url,
+    state: error ? "error" : feed.loading ? "loading" : "loaded",
+    ...(error && { error: error.message ?? String(error) }),
+    count: feed.data?.entry?.length ?? 0,
+  };
+};
+
+const byIndex = (a: ComponentRecord, b: ComponentRecord) =>
+  (a.index ?? 0) - (b.index ?? 0);
+
+/** Components in order, a group's children nested under it (they share the river and its indexes). */
+const describeComponents = (
+  mounted: ComponentRecord[],
+  belongs: (record: ComponentRecord) => boolean,
+  limit: number
+) =>
+  mounted
+    .filter(belongs)
+    .sort(byIndex)
+    .map((record) => {
+      const children = describeComponents(
+        mounted,
+        (child) => child.parentId === record.component.id,
+        limit
+      );
+
+      return {
+        index: record.index,
+        id: record.component.id,
+        type: record.component.component_type,
+        name: record.component.name,
+        feed: describeFeed(record.feed),
+        entries: (record.feed?.data?.entry ?? [])
+          .slice(0, limit)
+          .map((entry, index) => ({ index, id: entry.id, title: entry.title })),
+        ...(children.length > 0 && { children }),
+      };
+    });
+
+const describeRiverComponents = (mounted: ComponentRecord[], limit: number) => {
+  const ids = new Set(mounted.map((record) => record.component.id));
+
+  return describeComponents(
+    mounted,
+    (record) => !record.parentId || !ids.has(record.parentId),
+    limit
+  );
+};
+
+const describeScreen = (pathname: string, limit: number) => {
+  const state = routeState(pathname);
+  const { screen, entry, nested } = state;
+  const { kind, identifier } = describeKind(state);
+  const plugin = describePlugin(identifier);
+
+  const mounted = Array.from(records).filter(
+    (record) => record.pathname === pathname
+  );
+
+  const riverIds = R.uniq(mounted.map((record) => record.riverId));
+  const rivers = appStore.get("rivers") as Record<string, ZappRiver>;
+
+  return {
+    pathname,
+    screen: {
+      kind,
+      ...(screen && { id: screen.id, name: screen.name, type: screen.type }),
+      ...(plugin && { plugin }),
+    },
+    ...(nested?.screen && {
+      nested: {
+        id: nested.screen.id,
+        name: nested.screen.name,
+        type: nested.screen.type,
+      },
+    }),
+    entry: entry ? { id: entry.id, title: entry.title } : null,
+    rivers: riverIds.map((riverId) => ({
+      id: riverId,
+      name: rivers?.[riverId]?.name,
+      type: rivers?.[riverId]?.type,
+      components: describeRiverComponents(
+        mounted.filter((record) => record.riverId === riverId),
+        limit
+      ),
+    })),
+  };
+};
+
+const tools: XrayToolSpec[] = [
+  {
+    name: "current",
+    description:
+      "The screen on top (hooks modal, modal or bottom sheet, video modal unless docked, else stack top) " +
+      "or the one at `pathname`: what renders it (kind river, plugin, hook, player, link, favorites, " +
+      "bottomSheet, and the plugin), its river components in order (a group's children nested) with " +
+      "their feed (url, state, count) and first entries. " +
+      "Lists mount ahead of the viewport, so a component here may be off screen: use the native " +
+      "ui.inspect for what is visible (row testID component-<id>; cell testIDs contain the entry id).",
+    parameters: [
+      {
+        name: "pathname",
+        type: "string",
+        description:
+          "A mounted screen's route (see mounted); defaults to the top one.",
+      },
+      {
+        name: "limit",
+        type: "number",
+        description: `Entries per component, default ${DEFAULT_ENTRIES_LIMIT}.`,
+      },
+    ],
+    handler: ({ pathname, limit }) => {
+      const target =
+        typeof pathname === "string" && pathname ? pathname : getTopPathname();
+
+      if (!target) throw new Error("Navigation is not available yet");
+
+      return {
+        ...describeScreen(target, toLimit(limit)),
+        mounted: R.uniq(Array.from(records, (record) => record.pathname)),
+      };
+    },
+  },
+];
+
+const registerScreenToolbox = () =>
+  registerXrayToolbox({
+    name: "screen",
+    description:
+      "What the current screen shows: what renders it, river components, their feeds and entries.",
+    tools,
+  });
+
+/**
+ * Keeps a record of a mounted river component for the toolbox. Returns the record so the caller
+ * can attach the feed data it renders with.
+ */
+export const useScreenToolboxRecord = (
+  component: ZappUIComponent,
+  riverId: string,
+  index: number | undefined,
+  parentId: string | undefined,
+  pathname: string
+): ComponentRecord => {
+  const record = useMemo(
+    () => ({ component, riverId, index, parentId, pathname }),
+    [component, riverId, index, parentId, pathname]
+  );
+
+  useEffect(() => {
+    if (unavailable) return;
+
+    registerScreenToolbox().then((registered) => {
+      if (!registered) {
+        unavailable = true;
+        records.clear();
+      }
+    });
+
+    records.add(record);
+
+    return () => {
+      records.delete(record);
+    };
+  }, [record]);
+
+  return record;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-ui-components",
-  "version": "16.0.0-rc.113",
+  "version": "16.0.0-rc.114",
   "description": "Applicaster Zapp React Native ui components for the Quick Brick App",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,10 +28,10 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-bridge": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-redux": "16.0.0-rc.113",
-    "@applicaster/zapp-react-native-utils": "16.0.0-rc.113",
+    "@applicaster/applicaster-types": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-bridge": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-redux": "16.0.0-rc.114",
+    "@applicaster/zapp-react-native-utils": "16.0.0-rc.114",
     "fast-json-stable-stringify": "^2.1.0",
     "promise": "^8.3.0",
     "react-native-sortables": "1.7.1",