@applicaster/quick-brick-core 16.0.0-alpha.3081324238 → 16.0.0-alpha.3202041045

package/App/NavigationProvider/NavigationProvider.tsx

@@ -13,6 +13,8 @@ import {
   useGetScreenOrientation,
 } from "@applicaster/zapp-react-native-utils/appUtils/orientationHelper";
 import { focusManager } from "@applicaster/zapp-react-native-utils/focusManager/FocusManager";
+import { setXrayNavigator } from "@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator";
+import { registerNavToolbox } from "./navToolbox";
 
 import reducer, {
   ACTIONS,
@@ -760,11 +762,11 @@ export function NavigationProvider({ children }: Props) {
   const getStackForPathname = (
     pathname: string
   ): NavigationScreenState | undefined => {
-    const stack = [...state?.stack?.mainStack];
-
-    const currentStack = stack.find(({ route }) => route === pathname);
-
-    return currentStack;
+    // Topmost match: the active screen if a route is on the stack twice.
+    return R.findLast(
+      ({ route }) => route === pathname,
+      state?.stack?.mainStack ?? []
+    );
   };
 
   const navigator: QuickBrickAppNavigator = React.useMemo(
@@ -829,6 +831,13 @@ export function NavigationProvider({ children }: Props) {
     navigator.state = state;
   }
 
+  React.useLayoutEffect(() => {
+    setXrayNavigator(navigator);
+    registerNavToolbox();
+
+    return () => setXrayNavigator(undefined);
+  }, [navigator]);
+
   React.useLayoutEffect(() => {
     if (pathname === "/" && appLaunched) {
       goHome(true);

package/App/NavigationProvider/__tests__/navToolbox.test.ts

@@ -0,0 +1,227 @@
+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 {
+  playerManager,
+} = require("@applicaster/zapp-react-native-utils/appUtils/playerManager");
+
+const { registerNavToolbox } = require("../navToolbox");
+
+const navigator = (overrides = {}) => {
+  const nav = {
+    getPathname: () => "/river/a/river/b",
+    getStack: () => [{ route: "/river/a" }, { route: "/river/a/river/b" }],
+    canGoBack: () => true,
+    goBack: jest.fn(),
+    goHome: jest.fn(),
+    getPlayNextOverlay: () => null,
+    getModalState: () => modalStore.getState().modalState,
+    dismissModal: jest.fn(),
+    videoModalState: { visible: false },
+    minimiseVideoModal: jest.fn(),
+    maximiseVideoModal: jest.fn(),
+    closeVideoModal: jest.fn(),
+    ...overrides,
+  };
+
+  setXrayNavigator(nav as unknown as QuickBrickAppNavigator);
+
+  return nav;
+};
+
+const videoModal = (mode: string) => ({
+  videoModalState: { visible: true, mode, item: { id: "v1", title: "V" } },
+});
+
+const call = (name: string) => {
+  // Other toolboxes (player) may register first.
+  const { tools } = mockRegister.mock.calls.find(
+    ([toolbox]) => toolbox.name === "nav"
+  )[0];
+
+  return tools.find((tool) => tool.name === name).handler({});
+};
+
+describe("navToolbox", () => {
+  beforeAll(() => registerNavToolbox());
+
+  afterEach(() => {
+    modalStore.getState().setModalState({ visible: false, screen: null });
+    jest.restoreAllMocks();
+  });
+
+  it("throws until the NavigationProvider sets the navigator", () => {
+    setXrayNavigator(undefined);
+
+    expect(() => call("stack")).toThrow("Navigation is not available yet");
+  });
+
+  it("goes back one screen", () => {
+    const nav = navigator();
+
+    expect(call("back")).toEqual({ from: "/river/a/river/b", wentBack: true });
+    expect(nav.goBack).toHaveBeenCalledWith(false);
+  });
+
+  it("does not go back from the root", () => {
+    const nav = navigator({ canGoBack: () => false });
+
+    expect(call("back")).toMatchObject({ wentBack: false });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("does not pop the screen under a modal or the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(call("back")).toEqual({
+      from: "video-modal/v1",
+      wentBack: false,
+      blockedBy: "video-modal",
+    });
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("back")).toMatchObject({ blockedBy: "modal" });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("only dismisses Play Next when it shows", () => {
+    const nav = navigator({ getPlayNextOverlay: () => ({}) });
+
+    expect(call("back")).toMatchObject({
+      wentBack: false,
+      dismissed: "playNext",
+    });
+
+    expect(nav.goBack).toHaveBeenCalledWith(false);
+  });
+
+  it("leaves a hook screen to cancel itself", () => {
+    const nav = navigator({ getPathname: () => "/river/a/hooks/login" });
+
+    expect(call("back")).toMatchObject({ wentBack: false, blockedBy: "hook" });
+    expect(nav.goBack).not.toHaveBeenCalled();
+  });
+
+  it("goes home", () => {
+    const nav = navigator();
+
+    expect(call("home")).toEqual({ from: "/river/a/river/b", wentHome: true });
+    expect(nav.goHome).toHaveBeenCalled();
+  });
+
+  it("does not go home under a modal or the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(call("home")).toEqual({
+      from: "video-modal/v1",
+      wentHome: false,
+      blockedBy: "video-modal",
+    });
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("home")).toMatchObject({ blockedBy: "modal" });
+    expect(nav.goHome).not.toHaveBeenCalled();
+  });
+
+  it("goes home with the mini player docked", () => {
+    const nav = navigator(videoModal("MINIMIZED"));
+
+    expect(call("home")).toMatchObject({ wentHome: true });
+    expect(nav.goHome).toHaveBeenCalled();
+  });
+
+  it("dismisses the modal store's modal, not the video modal", () => {
+    const nav = navigator(videoModal("MAXIMIZED"));
+
+    expect(() => call("dismissModal")).toThrow("No modal is open");
+
+    modalStore.getState().openModal({ item: { id: "m" } });
+
+    expect(call("dismissModal")).toBe("OK");
+    expect(nav.dismissModal).toHaveBeenCalled();
+  });
+
+  it("minimises only a maximised video modal", () => {
+    const fullscreen = navigator(videoModal("FULLSCREEN"));
+
+    expect(() => call("minimizeVideoModal")).toThrow("mode is FULLSCREEN");
+    expect(fullscreen.minimiseVideoModal).not.toHaveBeenCalled();
+
+    const maximized = navigator(videoModal("MAXIMIZED"));
+
+    call("minimizeVideoModal");
+
+    expect(maximized.minimiseVideoModal).toHaveBeenCalled();
+  });
+
+  it("enters and leaves fullscreen through the player, which also rotates the phone", () => {
+    const invoke = jest.spyOn(playerManager, "invokeHandler");
+    const playerContainer = jest.fn();
+
+    playerManager.on("toggleFullscreen", playerContainer);
+
+    navigator(videoModal("MAXIMIZED"));
+    call("fullscreenVideoModal");
+
+    expect(invoke).toHaveBeenCalledWith("toggleFullscreen", {
+      fullscreen: true,
+    });
+
+    const fullscreen = navigator(videoModal("FULLSCREEN"));
+
+    call("maximizeVideoModal");
+
+    expect(invoke).toHaveBeenCalledWith("toggleFullscreen", {
+      fullscreen: false,
+    });
+
+    expect(fullscreen.maximiseVideoModal).not.toHaveBeenCalled();
+
+    playerManager.removeHandler("toggleFullscreen", playerContainer);
+  });
+
+  it("does not claim fullscreen without a player, or from the mini player", () => {
+    navigator(videoModal("MAXIMIZED"));
+
+    expect(() => call("fullscreenVideoModal")).toThrow("shows no player");
+
+    navigator(videoModal("MINIMIZED"));
+
+    expect(() => call("fullscreenVideoModal")).toThrow("mode is MINIMIZED");
+  });
+
+  it("expands the mini player", () => {
+    const nav = navigator(videoModal("MINIMIZED"));
+
+    call("maximizeVideoModal");
+
+    expect(nav.maximiseVideoModal).toHaveBeenCalled();
+  });
+
+  it("reports the video modal", () => {
+    navigator(videoModal("MINIMIZED"));
+
+    expect(call("videoModal")).toMatchObject({
+      visible: true,
+      mode: "MINIMIZED",
+      entry: { id: "v1", title: "V" },
+    });
+
+    navigator();
+
+    expect(call("videoModal")).toMatchObject({ visible: false });
+  });
+});

package/App/NavigationProvider/navToolbox.ts

@@ -0,0 +1,224 @@
+import { Dimensions } from "react-native";
+import {
+  registerXrayToolbox,
+  XrayToolSpec,
+} from "@applicaster/zapp-react-native-utils/logger/xrayToolbox";
+import { getXrayNavigator } from "@applicaster/zapp-react-native-utils/navigationUtils/xrayNavigator";
+import { playerManager } from "@applicaster/zapp-react-native-utils/appUtils/playerManager";
+import { getTopPathname } from "@applicaster/zapp-react-native-ui-components/Decorators/ZappPipesDataConnector/screenToolbox";
+
+/**
+ * X-Ray `nav.*` toolbox: lets an agent navigate by intent and read or drive the video modal,
+ * which is navigation state. The swipes behind some of these (minimising the player, dragging a
+ * sheet) are react-native-gesture-handler recognisers that no public API can feed touches to, so
+ * the outcome is offered instead. Pairs with `screen.current` to check where an action landed.
+ *
+ * Registered by the NavigationProvider, which keeps the navigator in a plain module variable
+ * (xrayNavigator), so updating it never renders anything.
+ */
+
+const requireNavigator = (): QuickBrickAppNavigator => {
+  const navigator = getXrayNavigator();
+
+  if (!navigator) throw new Error("Navigation is not available yet");
+
+  return navigator;
+};
+
+/** The player's own fullscreen switch: it also rotates the phone, as the fullscreen button does. */
+const toggleFullscreen = (fullscreen: boolean) => {
+  // Only a mounted PlayerContainer handles it: not while the video modal runs its hooks or casts.
+  if (!playerManager.hasHandler("toggleFullscreen")) {
+    throw new Error(
+      "The video modal shows no player (hooks running or casting)"
+    );
+  }
+
+  playerManager.invokeHandler("toggleFullscreen", { fullscreen });
+
+  return "OK: the player switches on its next tick, check with videoModal";
+};
+
+const requireVideoModal = () => {
+  const nav = requireNavigator();
+
+  if (!nav.videoModalState?.visible) {
+    throw new Error("No video modal is open");
+  }
+
+  return nav;
+};
+
+const tools: XrayToolSpec[] = [
+  {
+    name: "stack",
+    description: "Routes on the navigation stack, root first.",
+    handler: () => ({
+      routes: requireNavigator()
+        .getStack()
+        .map(({ route }) => route),
+    }),
+  },
+  {
+    name: "back",
+    description:
+      "Go back one screen, as the nav bar back button does: it pops the stack and does not run " +
+      "hardware back listeners (Android back key), so a screen plugin's own back handling is skipped. " +
+      "Not while a modal, the video modal (unless docked) or a hook screen is on top: blockedBy says " +
+      "which; close it first, or cancel a hook with the device back key. With Play Next showing it " +
+      "only dismisses that. Check with screen.current.",
+    handler: () => {
+      const nav = requireNavigator();
+      const from = getTopPathname() ?? nav.getPathname();
+
+      // A presented layer (hooks-modal/, modal/, video-modal/) is on top: popping the stack would
+      // change the screen underneath it, which the user's back never does.
+      if (!from.startsWith("/")) {
+        return { from, wentBack: false, blockedBy: from.split("/")[0] };
+      }
+
+      if (nav.getPlayNextOverlay()) {
+        nav.goBack(false);
+
+        return { from, wentBack: false, dismissed: "playNext" };
+      }
+
+      // The hook screen answers the user's back itself (cancels its flow); a pop would skip that.
+      if (from.split("/").slice(-2)[0] === "hooks") {
+        return { from, wentBack: false, blockedBy: "hook" };
+      }
+
+      if (!nav.canGoBack()) return { from, wentBack: false };
+
+      nav.goBack(false);
+
+      return { from, wentBack: true };
+    },
+  },
+  {
+    name: "home",
+    description:
+      "Go to the home screen. Not while a modal, the video modal (unless docked) or the hooks modal is " +
+      "on top: blockedBy says which; close it first. On TV it does not move focus to the top menu as " +
+      "the remote's home does.",
+    handler: () => {
+      const nav = requireNavigator();
+      const from = getTopPathname() ?? nav.getPathname();
+
+      // goHome only replaces the stack: a presented layer would stay on top of the home screen,
+      // and it covers the menu the user would press home in.
+      if (!from.startsWith("/")) {
+        return { from, wentHome: false, blockedBy: from.split("/")[0] };
+      }
+
+      nav.goHome();
+
+      return { from, wentHome: true };
+    },
+  },
+  {
+    name: "dismissModal",
+    description:
+      "Close the open modal screen or bottom sheet, as dragging it down does. Not the video modal: use closeVideoModal.",
+    handler: () => {
+      const nav = requireNavigator();
+
+      if (!nav.getModalState()?.visible) throw new Error("No modal is open");
+
+      nav.dismissModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "videoModal",
+    description:
+      "The video modal: visible, mode (MAXIMIZED, MINIMIZED = mini player, FULLSCREEN, PIP), its entry, " +
+      "and the screen orientation.",
+    handler: () => {
+      const videoModal = requireNavigator().videoModalState;
+      const { width, height } = Dimensions.get("window");
+      const orientation = width > height ? "landscape" : "portrait";
+
+      if (!videoModal?.visible) return { visible: false, orientation };
+
+      return {
+        visible: true,
+        mode: videoModal.mode,
+        entry: videoModal.item
+          ? { id: videoModal.item.id, title: videoModal.item.title }
+          : null,
+        orientation,
+      };
+    },
+  },
+  {
+    name: "minimizeVideoModal",
+    description:
+      "Minimise the maximised video modal to the mini player, as swiping it down does.",
+    handler: () => {
+      const nav = requireVideoModal();
+      const { mode } = nav.videoModalState;
+
+      // The swipe exists only on the maximised modal; other modes have no way to the mini player.
+      if (mode !== "MAXIMIZED") {
+        throw new Error(
+          `Only a maximised video modal minimises (mode is ${mode})`
+        );
+      }
+
+      nav.minimiseVideoModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "maximizeVideoModal",
+    description: "Expand the mini player or leave fullscreen.",
+    handler: () => {
+      const nav = requireVideoModal();
+
+      if (nav.videoModalState.mode === "FULLSCREEN") {
+        return toggleFullscreen(false);
+      }
+
+      nav.maximiseVideoModal();
+
+      return "OK";
+    },
+  },
+  {
+    name: "fullscreenVideoModal",
+    description:
+      "Put the video modal in fullscreen, as the player's fullscreen button does.",
+    handler: () => {
+      const { mode } = requireVideoModal().videoModalState;
+
+      // The fullscreen button is on the maximised player, not on the mini player.
+      if (mode !== "MAXIMIZED") {
+        throw new Error(
+          `Only a maximised video modal goes fullscreen (mode is ${mode})`
+        );
+      }
+
+      return toggleFullscreen(true);
+    },
+  },
+  {
+    name: "closeVideoModal",
+    description: "Close the video modal and its player.",
+    handler: () => {
+      requireVideoModal().closeVideoModal();
+
+      return "OK";
+    },
+  },
+];
+
+export const registerNavToolbox = () =>
+  registerXrayToolbox({
+    name: "nav",
+    description:
+      "Navigate the app (stack, back, home, modals) and drive the video modal.",
+    tools,
+  });

package/App/NavigationProvider/utils.ts

@@ -183,6 +183,27 @@ export function getNavigationTarget(
     data.entry = targetEntry;
   }
 
+  if (data.entry && !data.screen) {
+    const entryType = (data.entry.type as ZappEntryType)?.value;
+    const mappedScreenId = contentTypes?.[entryType]?.screen_id;
+
+    const mappedRiver = mappedScreenId ? rivers?.[mappedScreenId] : undefined;
+
+    if (!mappedScreenId) {
+      logger.error({
+        message: `getNavigationTarget: mapped screen ID missing for content type "${entryType}". Check your types mapping or screen configuration.`,
+        data: { entry: data.entry },
+      });
+    } else if (!mappedRiver) {
+      logger.error({
+        message: `getNavigationTarget: cannot map screen ID "${mappedScreenId}" to a river. Check your types mapping or screen configuration.`,
+        data: { entry: data.entry, mappedScreenId },
+      });
+    }
+
+    data.screen = mappedRiver;
+  }
+
   return data;
 }
 

package/App/index.tsx

@@ -33,6 +33,7 @@ import { LogicAggregatorContainer } from "./LogicAggregatorContainer";
 import { LoadingOverlay } from "./LoadingOverlay";
 import { NotificationToastRenderer } from "./NotificationToastRenderer";
 import { ZappAppWrapper } from "./components/ZappAppWrapper";
+import { registerCoreUIActions } from "./uiActions";
 
 interface AppOptions {
   Layout: React.ComponentType;
@@ -52,8 +53,10 @@ const App = ({
   OfflineHandler,
   SplashLoader,
   InteractionManager,
-}: AppOptions): ZappApp =>
-  React.memo(function ZappApp(props: AppComponentProps) {
+}: AppOptions): ZappApp => {
+  registerCoreUIActions();
+
+  return React.memo(function ZappApp(props: AppComponentProps) {
     const {
       styles,
       components: { AppContainer },
@@ -92,6 +95,7 @@ const App = ({
       </ZappAppWrapper>
     );
   });
+};
 
 export function createQuickBrickApp(options): ZappApp {
   const {

package/App/uiActions/index.ts

@@ -0,0 +1,13 @@
+import { isTV } from "@applicaster/zapp-react-native-utils/reactUtils";
+
+import { registerMuteUnmuteUIAction } from "./muteUnmute";
+
+/**
+ * App-wide UI actions owned by QuickBrick, registered once at startup.
+ * Actions scoped to a live object (e.g. player speed) register with their owner.
+ */
+export const registerCoreUIActions = (): (() => void) => {
+  const unregisters = isTV() ? [] : [registerMuteUnmuteUIAction()];
+
+  return () => unregisters.forEach((unregister) => unregister());
+};

package/App/uiActions/muteUnmute/__tests__/assetResolver.test.ts

@@ -0,0 +1,226 @@
+import {
+  resolveActionAssets,
+  resolveButtonAssets,
+  isConfiguredAsset,
+  firstConfiguredAsset,
+  selectActionAsset,
+  toFlavourTuple,
+} from "../assetResolver";
+import { ACTION_DEFAULT_ASSETS, BUTTON_DEFAULT_ASSETS } from "../defaultAssets";
+
+const createManifest = require("../../../../../../plugins/mute-unmute-action/manifests/manifest.config");
+
+// distinct value per slot, so a resolver mixing up flavours or states is caught.
+// The real defaults are covered by defaultAssets.test.ts
+jest.mock("../defaultAssets", () => {
+  const action = (f: string) => ({
+    mute: `action_${f}_mute`,
+    unmute: `action_${f}_unmute`,
+  });
+
+  const button = (f: string) => ({
+    mute: `button_${f}_mute`,
+    unmute: `button_${f}_unmute`,
+  });
+
+  return {
+    ACTION_DEFAULT_ASSETS: { flavour_1: action("1"), flavour_2: action("2") },
+    BUTTON_DEFAULT_ASSETS: { flavour_1: button("1"), flavour_2: button("2") },
+  };
+});
+
+const FLAVOURS = ["flavour_1", "flavour_2"];
+const ACTION_STATES = ["mute", "unmute"];
+const BUTTON_STATES = ["mute", "unmute"];
+
+const actionKey = (flavour: string, state: string) =>
+  `mobile_action_${flavour}_${state}_asset`;
+
+const buttonKey = (flavour: string, state: string) =>
+  `mobile_button_${flavour}_${state}_asset`;
+
+describe("isConfiguredAsset", () => {
+  it.each([
+    ["a URL", "https://x.com/a.png", true],
+    ["an empty string", "", false],
+    ["whitespace", "  \n", false],
+    ["undefined", undefined, false],
+    ["null", null, false],
+    ["a number", 5, false],
+    ["an object", {}, false],
+  ])("%s", (_, value, expected) => {
+    expect(isConfiguredAsset(value)).toBe(expected);
+  });
+});
+
+describe("firstConfiguredAsset", () => {
+  it("returns the first configured candidate", () => {
+    expect(firstConfiguredAsset(undefined, " ", "a", "b")).toBe("a");
+  });
+
+  it("returns undefined when nothing is configured", () => {
+    expect(firstConfiguredAsset(undefined, "", null)).toBeUndefined();
+    expect(firstConfiguredAsset()).toBeUndefined();
+  });
+});
+
+describe("resolveActionAssets", () => {
+  it("equals the defaults without configuration", () => {
+    expect(resolveActionAssets({ configuration: {} })).toEqual(
+      ACTION_DEFAULT_ASSETS
+    );
+  });
+
+  FLAVOURS.forEach((flavour) =>
+    ACTION_STATES.forEach((state) =>
+      it(`overrides ${flavour} ${state} on its own`, () => {
+        const result = resolveActionAssets({
+          configuration: { [actionKey(flavour, state)]: "plugin.png" },
+        });
+
+        const expected = JSON.parse(JSON.stringify(ACTION_DEFAULT_ASSETS));
+        expected[flavour][state] = "plugin.png";
+        expect(result).toEqual(expected);
+      })
+    )
+  );
+
+  it("never returns an empty URI", () => {
+    const blank = (keys: string[]) =>
+      Object.fromEntries(keys.map((key) => [key, " "]));
+
+    const configuration = blank(
+      FLAVOURS.flatMap((f) => [
+        ...ACTION_STATES.map((s) => actionKey(f, s)),
+        ...BUTTON_STATES.map((s) => buttonKey(f, s)),
+      ])
+    );
+
+    const values = [
+      ...Object.values(
+        resolveActionAssets({
+          configuration,
+        })
+      ),
+      ...Object.values(resolveButtonAssets({ configuration })),
+    ].flatMap((assets) => Object.values(assets));
+
+    values.forEach((value) => expect(isConfiguredAsset(value)).toBe(true));
+  });
+
+  it("applies a plugin override to its own key and flavour only", () => {
+    const result = resolveActionAssets({
+      configuration: { [actionKey("flavour_2", "unmute")]: "plugin.png" },
+    });
+
+    expect(result.flavour_2.unmute).toBe("plugin.png");
+    expect(result.flavour_2.mute).toBe(ACTION_DEFAULT_ASSETS.flavour_2.mute);
+    expect(result.flavour_1).toEqual(ACTION_DEFAULT_ASSETS.flavour_1);
+  });
+
+  it("falls through whitespace plugin values", () => {
+    const result = resolveActionAssets({
+      configuration: {
+        [actionKey("flavour_1", "mute")]: "plugin.png",
+        [actionKey("flavour_1", "unmute")]: "  ",
+      },
+    });
+
+    expect(result.flavour_1.mute).toBe("plugin.png");
+
+    expect(result.flavour_1.unmute).toBe(
+      ACTION_DEFAULT_ASSETS.flavour_1.unmute
+    );
+  });
+});
+
+describe("resolveButtonAssets", () => {
+  it("equals the defaults without configuration", () => {
+    expect(resolveButtonAssets({ configuration: {} })).toEqual(
+      BUTTON_DEFAULT_ASSETS
+    );
+  });
+
+  FLAVOURS.forEach((flavour) =>
+    BUTTON_STATES.forEach((state) =>
+      it(`overrides ${flavour} ${state} on its own`, () => {
+        const result = resolveButtonAssets({
+          configuration: { [buttonKey(flavour, state)]: "plugin.png" },
+        });
+
+        const expected = JSON.parse(JSON.stringify(BUTTON_DEFAULT_ASSETS));
+        expected[flavour][state] = "plugin.png";
+        expect(result).toEqual(expected);
+      })
+    )
+  );
+
+  it("falls back for whitespace values", () => {
+    const result = resolveButtonAssets({
+      configuration: { [buttonKey("flavour_1", "mute")]: " " },
+    });
+
+    expect(result).toEqual(BUTTON_DEFAULT_ASSETS);
+  });
+});
+
+describe("select helpers", () => {
+  const action = { mute: "m", unmute: "u" };
+
+  it.each([
+    [false, "m"],
+    [true, "u"],
+  ])("selectActionAsset muted=%p -> %s", (muted, expected) => {
+    expect(selectActionAsset(action, muted)).toBe(expected);
+  });
+});
+
+describe("toFlavourTuple", () => {
+  it("returns [flavour_1, flavour_2] picks", () => {
+    expect(
+      toFlavourTuple(
+        { flavour_1: { v: "a" }, flavour_2: { v: "b" } },
+        (x) => x.v
+      )
+    ).toEqual(["a", "b"]);
+  });
+});
+
+describe("manifest key contract", () => {
+  const manifestKeys = createManifest({
+    platform: "ios_for_quickbrick",
+    version: "1.0.0",
+  })
+    .custom_configuration_fields.flatMap((group) => group.fields)
+    .filter((field) => field.type === "uploader")
+    .map((field) => field.key)
+    .sort();
+
+  const readKeys = () => {
+    const read = new Set<string>();
+
+    const configuration = new Proxy(
+      {},
+      {
+        get: (_, key) => {
+          read.add(String(key));
+
+          return undefined;
+        },
+      }
+    );
+
+    resolveActionAssets({ configuration });
+    resolveButtonAssets({ configuration });
+
+    return [...read].sort();
+  };
+
+  it("reads exactly the uploader keys defined in the manifest", () => {
+    expect(readKeys()).toEqual(manifestKeys);
+
+    expect(manifestKeys).toHaveLength(
+      FLAVOURS.length * (ACTION_STATES.length + BUTTON_STATES.length)
+    );
+  });
+});

package/App/uiActions/muteUnmute/__tests__/binding.test.ts

@@ -0,0 +1,51 @@
+jest.mock("@applicaster/zapp-react-native-utils/pluginUtils", () => ({
+  getPluginByIdentifier: () => undefined,
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/reactHooks/usePluginConfiguration",
+  () => ({ getPluginConfiguration: () => ({}) })
+);
+
+jest.mock(
+  "@applicaster/zapp-react-native-ui-components/Components/VideoLive/MuteUnmuteController",
+  () => ({
+    MUTE_UNMUTE_ACTION_IDENTIFIER: "mute_unmute_action",
+    muteUnmuteController: {
+      getEntryState: () => ({ muted: true }),
+      subscribe: jest.fn(() => jest.fn()),
+      toggle: jest.fn(),
+    },
+  })
+);
+
+import { muteUnmuteUIAction } from "../index";
+import { muteUnmuteController } from "@applicaster/zapp-react-native-ui-components/Components/VideoLive/MuteUnmuteController";
+
+it("uses bundled visuals on the first read without a configuration plugin", () => {
+  expect(muteUnmuteUIAction.initialEntryState({ id: "1" })).toEqual(
+    expect.objectContaining({ checked: true, state: 1, label: "Unmute" })
+  );
+});
+
+it("delegates the command without a second imperative UI update", () => {
+  const updateState = jest.fn();
+  muteUnmuteUIAction.invokeAction({ id: "1" }, { updateState });
+  expect(muteUnmuteController.toggle).toHaveBeenCalledWith("1");
+  expect(updateState).not.toHaveBeenCalled();
+});
+
+it("hydrates a late subscriber and cleans up its controller subscription", () => {
+  const listener = jest.fn();
+  const remove = muteUnmuteUIAction.addListener("1", listener);
+
+  const controllerRemove = jest.mocked(muteUnmuteController.subscribe).mock
+    .results[0].value;
+
+  expect(listener).toHaveBeenCalledWith(
+    expect.objectContaining({ checked: true })
+  );
+
+  remove();
+  expect(controllerRemove).toHaveBeenCalledTimes(1);
+});

package/App/uiActions/muteUnmute/__tests__/defaultAssets.test.ts

@@ -0,0 +1,47 @@
+import { Image } from "react-native";
+
+jest
+  .spyOn(Image, "resolveAssetSource")
+  .mockReturnValue({ uri: "asset://mock" } as any);
+
+// imports are hoisted above the spy, so the module is loaded after it is set up
+const {
+  ACTION_DEFAULT_ASSETS,
+  BUTTON_DEFAULT_ASSETS,
+} = require("../defaultAssets");
+
+const FLAVOURS = ["flavour_1", "flavour_2"];
+const ACTION_STATES = ["mute", "unmute"];
+const BUTTON_STATES = ["mute", "unmute"];
+
+describe("defaultAssets", () => {
+  it("defines a non-empty action asset for every flavour and state", () => {
+    expect(Object.keys(ACTION_DEFAULT_ASSETS).sort()).toEqual(FLAVOURS);
+
+    FLAVOURS.forEach((flavour) => {
+      const assets = ACTION_DEFAULT_ASSETS[flavour];
+
+      expect(Object.keys(assets).sort()).toEqual([...ACTION_STATES].sort());
+
+      ACTION_STATES.forEach((state) => {
+        expect(typeof assets[state]).toBe("string");
+        expect(assets[state].length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  it("defines a non-empty button asset for every flavour and state", () => {
+    expect(Object.keys(BUTTON_DEFAULT_ASSETS).sort()).toEqual(FLAVOURS);
+
+    FLAVOURS.forEach((flavour) => {
+      const assets = BUTTON_DEFAULT_ASSETS[flavour];
+
+      expect(Object.keys(assets).sort()).toEqual([...BUTTON_STATES].sort());
+
+      BUTTON_STATES.forEach((state) => {
+        expect(typeof assets[state]).toBe("string");
+        expect(assets[state].length).toBeGreaterThan(0);
+      });
+    });
+  });
+});

package/App/uiActions/muteUnmute/__tests__/entryState.test.ts

@@ -0,0 +1,57 @@
+import { buildEntryState } from "../entryState";
+
+const actionAssets = {
+  flavour_1: { mute: "a1_mute", unmute: "a1_unmute" },
+  flavour_2: { mute: "a2_mute", unmute: "a2_unmute" },
+};
+
+const buttonAssets = {
+  flavour_1: { mute: "b1_mute", unmute: "b1_unmute" },
+  flavour_2: { mute: "b2_mute", unmute: "b2_unmute" },
+};
+
+const labels = { mute: "Mute", unmute: "Unmute" };
+
+const build = (muted: boolean) =>
+  buildEntryState({ state: { muted }, actionAssets, buttonAssets, labels });
+
+describe("buildEntryState", () => {
+  it("sound on: Mute icons, state 0", () => {
+    expect(build(false)).toEqual({
+      state: 0,
+      asset: ["a1_mute", "a2_mute"],
+      mobileButtonAssets: ["b1_mute", "b2_mute"],
+      label: "Mute",
+      checked: false,
+      visibleInCells: [],
+    });
+  });
+
+  it("muted: Unmute icons, state 1", () => {
+    expect(build(true)).toEqual({
+      state: 1,
+      asset: ["a1_unmute", "a2_unmute"],
+      mobileButtonAssets: ["b1_unmute", "b2_unmute"],
+      label: "Unmute",
+      checked: true,
+      visibleInCells: [],
+    });
+  });
+
+  it("limits cell actions to the playing instance without removing button assets", () => {
+    expect(
+      buildEntryState({
+        state: { muted: true, activeCellId: "playing-cell" },
+        actionAssets,
+        buttonAssets,
+        labels,
+      })
+    ).toEqual(
+      expect.objectContaining({
+        visibleInCells: ["playing-cell"],
+        mobileButtonAssets: ["b1_unmute", "b2_unmute"],
+        label: "Unmute",
+      })
+    );
+  });
+});

package/App/uiActions/muteUnmute/__tests__/labelResolver.test.ts

@@ -0,0 +1,35 @@
+import { DEFAULT_LABELS, resolveLabels, selectLabel } from "../labelResolver";
+
+describe("labelResolver", () => {
+  it("defaults to Mute / Unmute", () => {
+    expect(DEFAULT_LABELS).toEqual({ mute: "Mute", unmute: "Unmute" });
+    expect(resolveLabels()).toEqual(DEFAULT_LABELS);
+    expect(resolveLabels({})).toEqual(DEFAULT_LABELS);
+  });
+
+  it("uses configured values", () => {
+    expect(
+      resolveLabels({ mute_label: "Silence", unmute_label: "Sound on" })
+    ).toEqual({ mute: "Silence", unmute: "Sound on" });
+  });
+
+  it("falls back to the default for empty or whitespace values", () => {
+    expect(resolveLabels({ mute_label: "", unmute_label: "   " })).toEqual(
+      DEFAULT_LABELS
+    );
+  });
+
+  it("overrides each label independently", () => {
+    expect(resolveLabels({ unmute_label: "Sound on" })).toEqual({
+      mute: "Mute",
+      unmute: "Sound on",
+    });
+  });
+
+  it("selects the label describing the next action", () => {
+    const labels = { mute: "M", unmute: "U" };
+
+    expect(selectLabel(labels, false)).toBe("M");
+    expect(selectLabel(labels, true)).toBe("U");
+  });
+});

package/App/uiActions/muteUnmute/assetResolver.ts

@@ -0,0 +1,87 @@
+import { ACTION_DEFAULT_ASSETS, BUTTON_DEFAULT_ASSETS } from "./defaultAssets";
+import type {
+  ActionAssets,
+  ButtonAssets,
+  Flavour,
+  MuteUnmuteActionConfiguration,
+} from "./types";
+
+export const isConfiguredAsset = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+export const firstConfiguredAsset = (
+  ...candidates: unknown[]
+): string | undefined => candidates.find(isConfiguredAsset);
+
+// The only place in runtime code that defines the manifest key format.
+const pluginAsset = (
+  configuration: MuteUnmuteActionConfiguration | undefined,
+  kind: "action" | "button",
+  flavour: Flavour,
+  state: keyof ButtonAssets
+): unknown => configuration?.[`mobile_${kind}_${flavour}_${state}_asset`];
+
+const resolveAsset = (fallback: string, ...candidates: unknown[]): string =>
+  firstConfiguredAsset(...candidates) ?? fallback;
+
+export const resolveActionAssets = ({
+  configuration,
+}: {
+  configuration?: MuteUnmuteActionConfiguration;
+}): Record<Flavour, ActionAssets> => {
+  const forFlavour = (flavour: Flavour): ActionAssets => {
+    const defaults = ACTION_DEFAULT_ASSETS[flavour];
+
+    return {
+      mute: resolveAsset(
+        defaults.mute,
+        pluginAsset(configuration, "action", flavour, "mute")
+      ),
+      unmute: resolveAsset(
+        defaults.unmute,
+        pluginAsset(configuration, "action", flavour, "unmute")
+      ),
+    };
+  };
+
+  return {
+    flavour_1: forFlavour("flavour_1"),
+    flavour_2: forFlavour("flavour_2"),
+  };
+};
+
+export const resolveButtonAssets = ({
+  configuration,
+}: {
+  configuration?: MuteUnmuteActionConfiguration;
+}): Record<Flavour, ButtonAssets> => {
+  const forFlavour = (flavour: Flavour): ButtonAssets => {
+    const defaults = BUTTON_DEFAULT_ASSETS[flavour];
+
+    const asset = (state: keyof ButtonAssets) =>
+      resolveAsset(
+        defaults[state],
+        pluginAsset(configuration, "button", flavour, state)
+      );
+
+    return {
+      mute: asset("mute"),
+      unmute: asset("unmute"),
+    };
+  };
+
+  return {
+    flavour_1: forFlavour("flavour_1"),
+    flavour_2: forFlavour("flavour_2"),
+  };
+};
+
+export const selectActionAsset = (
+  assets: ActionAssets,
+  muted: boolean
+): string => (muted ? assets.unmute : assets.mute);
+
+export const toFlavourTuple = <T>(
+  byFlavour: Record<Flavour, T>,
+  pick: (assets: T) => string
+): [string, string] => [pick(byFlavour.flavour_1), pick(byFlavour.flavour_2)];

package/App/uiActions/muteUnmute/defaultAssets.ts

@@ -0,0 +1,44 @@
+import { resolveDefaultAssetUri } from "@applicaster/zapp-react-native-utils/actionUtils";
+import { getQuickBrickAsset } from "@applicaster/zapp-react-native-utils/quickBrickAssets";
+
+import type { ActionAssets, ButtonAssets, Flavour } from "./types";
+
+const PLUGIN = "mute_unmute_action";
+
+export const ACTION_DEFAULT_ASSETS: Record<Flavour, ActionAssets> = {
+  flavour_1: {
+    mute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "action/flavour_1/mute.png")
+    ),
+    unmute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "action/flavour_1/unmute.png")
+    ),
+  },
+  flavour_2: {
+    mute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "action/flavour_2/mute.png")
+    ),
+    unmute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "action/flavour_2/unmute.png")
+    ),
+  },
+};
+
+export const BUTTON_DEFAULT_ASSETS: Record<Flavour, ButtonAssets> = {
+  flavour_1: {
+    mute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "button/flavour_1/mute.png")
+    ),
+    unmute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "button/flavour_1/unmute.png")
+    ),
+  },
+  flavour_2: {
+    mute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "button/flavour_2/mute.png")
+    ),
+    unmute: resolveDefaultAssetUri(
+      getQuickBrickAsset(PLUGIN, "button/flavour_2/unmute.png")
+    ),
+  },
+};

package/App/uiActions/muteUnmute/entryState.ts

@@ -0,0 +1,28 @@
+import { selectActionAsset, toFlavourTuple } from "./assetResolver";
+import { selectLabel } from "./labelResolver";
+import type { ActionAssets, ButtonAssets, Flavour, Labels } from "./types";
+import type { MuteUnmuteEntryState } from "@applicaster/zapp-react-native-ui-components/Components/VideoLive/MuteUnmuteController";
+
+type BuildEntryStateArgs = {
+  state: MuteUnmuteEntryState;
+  actionAssets: Record<Flavour, ActionAssets>;
+  buttonAssets: Record<Flavour, ButtonAssets>;
+  labels: Labels;
+};
+
+export const buildEntryState = ({
+  state: { muted, activeCellId },
+  actionAssets,
+  buttonAssets,
+  labels,
+}: BuildEntryStateArgs): CellActionEntryState => ({
+  // Legacy player convention: state 1 = muted (shows the Unmute icon).
+  state: muted ? 1 : 0,
+  asset: toFlavourTuple(actionAssets, (a) => selectActionAsset(a, muted)),
+  mobileButtonAssets: toFlavourTuple(buttonAssets, (a) =>
+    selectActionAsset(a, muted)
+  ),
+  label: selectLabel(labels, muted),
+  checked: muted,
+  visibleInCells: activeCellId ? [activeCellId] : [],
+});

package/App/uiActions/muteUnmute/index.ts

@@ -0,0 +1,79 @@
+import { getPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
+import { getPluginConfiguration } from "@applicaster/zapp-react-native-utils/reactHooks/usePluginConfiguration";
+import {
+  uiActionsRegistry,
+  type RegisteredActionValue,
+} from "@applicaster/zapp-react-native-utils/uiActionsRegistrator/registry";
+
+import {
+  MUTE_UNMUTE_ACTION_IDENTIFIER,
+  muteUnmuteController,
+  type MuteUnmuteEntryState,
+} from "@applicaster/zapp-react-native-ui-components/Components/VideoLive/MuteUnmuteController";
+import { resolveActionAssets, resolveButtonAssets } from "./assetResolver";
+import { resolveLabels } from "./labelResolver";
+import { buildEntryState } from "./entryState";
+import type {
+  MuteUnmuteActionConfiguration,
+  MuteUnmuteActionLocalizations,
+} from "./types";
+
+type Assets = Pick<
+  Parameters<typeof buildEntryState>[0],
+  "actionAssets" | "buttonAssets"
+>;
+
+let cache: { plugin: unknown; assets: Assets } | null = null;
+
+// The `mute_unmute_action` plugin is configuration only: assets and labels.
+// Raw values are read because every field is optional and has a bundled default.
+const getVisuals = () => {
+  const plugin = getPluginByIdentifier(MUTE_UNMUTE_ACTION_IDENTIFIER, true);
+
+  if (!cache || cache.plugin !== plugin) {
+    const configuration = (plugin as any)?.configuration as
+      | MuteUnmuteActionConfiguration
+      | undefined;
+
+    cache = {
+      plugin,
+      assets: {
+        actionAssets: resolveActionAssets({ configuration }),
+        buttonAssets: resolveButtonAssets({ configuration }),
+      },
+    };
+  }
+
+  // Not cached: the locale can change at runtime.
+  const { localizations } = getPluginConfiguration<
+    unknown,
+    MuteUnmuteActionLocalizations
+  >(plugin);
+
+  return { ...cache.assets, labels: resolveLabels(localizations) };
+};
+
+const toEntryState = (state: MuteUnmuteEntryState) =>
+  buildEntryState({ state, ...getVisuals() });
+
+/** Visual binding: maps controller state to what cells and buttons render. */
+export const muteUnmuteUIAction: RegisteredActionValue = {
+  initialEntryState: (item) =>
+    toEntryState(muteUnmuteController.getEntryState(String(item.id))),
+  addListener: (entryId, listener) => {
+    const remove = muteUnmuteController.subscribe(String(entryId), (state) =>
+      listener(toEntryState(state))
+    );
+
+    listener(toEntryState(muteUnmuteController.getEntryState(String(entryId))));
+
+    return remove;
+  },
+  invokeAction: (item) => muteUnmuteController.toggle(String(item.id)),
+};
+
+export const registerMuteUnmuteUIAction = () =>
+  uiActionsRegistry.registerAction(
+    MUTE_UNMUTE_ACTION_IDENTIFIER,
+    muteUnmuteUIAction
+  );

package/App/uiActions/muteUnmute/labelResolver.ts

@@ -0,0 +1,15 @@
+import { firstConfiguredAsset } from "./assetResolver";
+import type { Labels, MuteUnmuteActionLocalizations } from "./types";
+
+export const DEFAULT_LABELS: Labels = { mute: "Mute", unmute: "Unmute" };
+
+export const resolveLabels = (
+  localizations?: MuteUnmuteActionLocalizations
+): Labels => ({
+  mute: firstConfiguredAsset(localizations?.mute_label) ?? DEFAULT_LABELS.mute,
+  unmute:
+    firstConfiguredAsset(localizations?.unmute_label) ?? DEFAULT_LABELS.unmute,
+});
+
+export const selectLabel = (labels: Labels, muted: boolean): string =>
+  muted ? labels.unmute : labels.mute;

package/App/uiActions/muteUnmute/types.ts

@@ -0,0 +1,18 @@
+export type Flavour = "flavour_1" | "flavour_2";
+
+export type ActionAssets = { mute: string; unmute: string };
+
+export type ButtonAssets = ActionAssets;
+
+export type Labels = { mute: string; unmute: string };
+
+type MobileKind = "action" | "button";
+
+export type MuteUnmuteActionConfiguration = Partial<
+  Record<`mobile_${MobileKind}_${Flavour}_${keyof ButtonAssets}_asset`, string>
+>;
+
+export type MuteUnmuteActionLocalizations = {
+  mute_label?: string;
+  unmute_label?: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/quick-brick-core",
-  "version": "16.0.0-alpha.3081324238",
+  "version": "16.0.0-alpha.3202041045",
   "description": "Core package for Applicaster's Quick Brick App",
   "main": "index.js",
   "types": "index.d.ts",
@@ -28,13 +28,13 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-alpha.3081324238",
-    "@applicaster/quick-brick-core-plugins": "16.0.0-alpha.3081324238",
-    "@applicaster/zapp-pipes-v2-client": "16.0.0-alpha.3081324238",
-    "@applicaster/zapp-react-native-bridge": "16.0.0-alpha.3081324238",
-    "@applicaster/zapp-react-native-redux": "16.0.0-alpha.3081324238",
-    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.3081324238",
-    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.3081324238",
+    "@applicaster/applicaster-types": "16.0.0-alpha.3202041045",
+    "@applicaster/quick-brick-core-plugins": "16.0.0-alpha.3202041045",
+    "@applicaster/zapp-pipes-v2-client": "16.0.0-alpha.3202041045",
+    "@applicaster/zapp-react-native-bridge": "16.0.0-alpha.3202041045",
+    "@applicaster/zapp-react-native-redux": "16.0.0-alpha.3202041045",
+    "@applicaster/zapp-react-native-ui-components": "16.0.0-alpha.3202041045",
+    "@applicaster/zapp-react-native-utils": "16.0.0-alpha.3202041045",
     "atob": "^2.1.2",
     "axios": "^0.28.0",
     "btoa": "^1.2.1",