@applicaster/quick-brick-core 16.0.0-rc.99 → 17.0.0-rc.1

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

@@ -7,16 +7,16 @@ import {
 } from "@applicaster/zapp-react-native-utils/navigationUtils";
 import { findPluginByType } from "@applicaster/zapp-react-native-utils/pluginUtils";
 
-import { coreAppLogger } from "../logger";
 import { isString } from "@applicaster/zapp-react-native-utils/stringUtils";
 import { SCREEN_TYPES } from "@applicaster/zapp-react-native-utils/navigationUtils/itemTypes";
 import { isNilOrEmpty } from "@applicaster/zapp-react-native-utils/reactUtils/helpers";
+import { subsystemLogger } from "@applicaster/zapp-react-native-utils/logger";
 
 const EXTERNAL_URL_TYPE = "external_url";
 const EXTERNAL_URL_FLAG = "open_external_url";
 const WEBVIEW_SCREEN_IDENTIFIER = "webview_screen_qb";
 
-const logger = coreAppLogger.addSubsystem("Navigator");
+const logger = subsystemLogger("ui/navigation", "Navigator");
 
 /**
  * Drops a leading `/hooks/<screen_id>` segment from a path.
@@ -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/NetworkStatusProvider/NetworkStatusProvider.tsx

@@ -13,6 +13,12 @@ import {
 } from "./utils";
 import { usePrevious } from "@applicaster/zapp-react-native-utils/reactHooks/utils";
 
+import { useResumeVerifiedNetInfo } from "./useResumeVerifiedNetInfo";
+import { describeNetInfo } from "./resumeVerification";
+import { subsystemLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const logger = subsystemLogger("network/reachability", "NetworkStatusProvider");
+
 // Use default netInfo config for all platforms (important for web platform which otherwise
 // will use backend root which is not responding for HEAD request)
 if (["web", "lg_tv", "samsung_tv"].includes(Platform.OS)) {
@@ -36,10 +42,30 @@ export const NetworkStatusProvider = ({
   // NetInfo library does not have accurate information for Tizen SmartTVs, and possibly WebOS
   // This combined info helps us gather data from the native connection status APIs
   // and includes it in our definition of... online.
-  const combinedNetInfo: NetInfoState & { deviceStatus?: NetStatus } = {
-    ...currentNetInfo,
-    deviceStatus,
-  };
+  // stable reference between real changes: every new reference is a network update
+  const liveNetInfo = React.useMemo<
+    NetInfoState & { deviceStatus?: NetStatus }
+  >(
+    () => ({ ...currentNetInfo, deviceStatus }),
+    [currentNetInfo, deviceStatus]
+  );
+
+  // NetInfo reports stale offline status right after resume/unlock (iOS),
+  // publish the network status verified after the app returns to foreground
+  const { netInfo: verifiedNetInfo, stillOfflineAfterResumeCount } =
+    useResumeVerifiedNetInfo(liveNetInfo);
+
+  // Memoized so consumers only re-render when the published status changes,
+  // not on every render of this provider
+  const combinedNetInfo = React.useMemo<
+    NetInfoState & {
+      deviceStatus?: NetStatus;
+      stillOfflineAfterResumeCount: number;
+    }
+  >(
+    () => ({ ...verifiedNetInfo, stillOfflineAfterResumeCount }),
+    [verifiedNetInfo, stillOfflineAfterResumeCount]
+  );
 
   const { onConnectionTypeChanged, onConnectionLost, onConnectionRestored } =
     React.useMemo<NetworkHooks>(() => getNetworkHooks(plugins), []);
@@ -57,6 +83,16 @@ export const NetworkStatusProvider = ({
     if (!combinedNetInfo.details) return;
 
     if (previousOnline !== undefined && previousOnline !== online) {
+      logger.info({
+        message: "NetworkStatus: online status changed",
+        data: {
+          online,
+          previousOnline,
+          published: describeNetInfo(combinedNetInfo),
+          live: describeNetInfo(liveNetInfo),
+        },
+      });
+
       online
         ? onConnectionRestored &&
           callAllWith(onConnectionRestored, combinedNetInfo)

package/App/NetworkStatusProvider/ResumeVerificationController.ts

@@ -0,0 +1,282 @@
+import { AppState, AppStateStatus } from "react-native";
+import { NetInfoState } from "@react-native-community/netinfo";
+
+import { isOnline } from "./utils";
+import {
+  RESUME_VERIFICATION_DELAY_MS,
+  describeNetInfo,
+  getResumeDecision,
+  isBackgroundAppState,
+  isResumeVerificationEnabled,
+} from "./resumeVerification";
+import { subsystemLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const logger = subsystemLogger("network/reachability", "NetworkStatusProvider");
+
+export type ConnectionInfo = NetInfoState & { deviceStatus?: NetStatus };
+
+export type ResumeVerifiedState<T extends ConnectionInfo> = {
+  netInfo: T;
+  stillOfflineAfterResumeCount: number;
+};
+
+type Phase = "live" | "frozen" | "verifying";
+
+/**
+ * Holds the published network status while the app is in background and for
+ * RESUME_VERIFICATION_DELAY_MS after it becomes active again, then publishes the
+ * current state. Works around stale iOS NetInfo reachability failures on resume/unlock.
+ *
+ * start()/stop() manage the AppState subscription and timer (useLayoutEffect),
+ * setNetInfo() feeds live NetInfo, subscribe()/getState() back useSyncExternalStore.
+ */
+export class ResumeVerificationController<T extends ConnectionInfo> {
+  private phase: Phase = "live";
+  private appState: AppStateStatus;
+  private live: T;
+  private state: ResumeVerifiedState<T>;
+  private listeners = new Set<() => void>();
+  private subscription: { remove: () => void } | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * @param initialNetInfo - live NetInfo at mount, published as the initial state.
+   * Starts "frozen" when the app is created in background (e.g. iOS background launch).
+   */
+  constructor(initialNetInfo: T) {
+    this.appState = AppState.currentState;
+    this.live = initialNetInfo;
+    this.state = { netInfo: initialNetInfo, stillOfflineAfterResumeCount: 0 };
+
+    if (isResumeVerificationEnabled() && isBackgroundAppState(this.appState)) {
+      this.phase = "frozen";
+    }
+
+    this.subscribe = this.subscribe.bind(this);
+    this.getState = this.getState.bind(this);
+    this.applyAppState = this.applyAppState.bind(this);
+  }
+
+  /**
+   * useSyncExternalStore subscribe: listener is called whenever getState() changes.
+   * @param listener - called with no arguments after each publish
+   * @returns unsubscribe function
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * useSyncExternalStore snapshot: same reference until a new state is published.
+   * @returns the verified network status and the still-offline-after-resume counter
+   */
+  getState(): ResumeVerifiedState<T> {
+    return this.state;
+  }
+
+  /**
+   * Subscribes to AppState changes and catches up with the current app state.
+   * Idempotent; no-op on platforms without resume verification (web, TV).
+   * Call from useLayoutEffect, paired with stop().
+   */
+  start(): void {
+    if (!isResumeVerificationEnabled() || this.subscription) return;
+
+    this.subscription = AppState.addEventListener("change", this.applyAppState);
+
+    // AppState may have changed since construction (e.g. initial "background"
+    // corrected to "active"), or stop() interrupted a window: catch up
+    this.applyAppState(AppState.currentState);
+  }
+
+  /**
+   * Removes the AppState subscription and cancels a pending verification.
+   * An interrupted window falls back to "frozen" and restarts on the next start() while active.
+   */
+  stop(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+    this.clearTimer();
+
+    // an interrupted window is restarted by the next start() while active
+    if (this.phase === "verifying") {
+      this.phase = "frozen";
+    }
+  }
+
+  /**
+   * Feeds the latest live NetInfo. Published immediately while "live",
+   * held (and logged as ignored) while "frozen" or "verifying".
+   * @param netInfo - live NetInfo; the same reference is a no-op
+   */
+  setNetInfo(netInfo: T): void {
+    if (netInfo === this.live) return;
+
+    this.live = netInfo;
+
+    if (this.phase === "live") {
+      this.publish(netInfo);
+
+      return;
+    }
+
+    logger.info({
+      message: "NetworkStatus: network change ignored until verified",
+      data: {
+        appState: this.appState,
+        phase: this.phase,
+        published: describeNetInfo(this.state.netInfo),
+        live: describeNetInfo(netInfo),
+      },
+    });
+  }
+
+  /**
+   * AppState change handler: "background" freezes, "active" after a freeze starts verification,
+   * anything else ("inactive", "unknown") keeps the current phase.
+   * @param nextAppState - new AppState value
+   */
+  private applyAppState(nextAppState: AppStateStatus): void {
+    const previousAppState = this.appState;
+    const nextPhase = this.getNextPhase(nextAppState);
+    this.appState = nextAppState;
+
+    if (previousAppState === nextAppState && nextPhase === this.phase) return;
+
+    logger.info({
+      message: "NetworkStatus: app state changed",
+      data: {
+        appState: nextAppState,
+        previousAppState,
+        phase: this.phase,
+        nextPhase,
+        published: describeNetInfo(this.state.netInfo),
+        live: describeNetInfo(this.live),
+      },
+    });
+
+    if (nextPhase === "frozen" && this.phase !== "frozen") {
+      this.freeze();
+    } else if (nextPhase === "verifying" && this.phase === "frozen") {
+      this.startVerification();
+    }
+  }
+
+  /**
+   * @param appState - new AppState value
+   * @returns the phase the controller moves to for this app state
+   */
+  private getNextPhase(appState: AppStateStatus): Phase {
+    if (isBackgroundAppState(appState)) return "frozen";
+
+    if (appState === "active" && this.phase === "frozen") return "verifying";
+
+    return this.phase;
+  }
+
+  /**
+   * Stops publishing live changes; cancels a running verification window.
+   */
+  private freeze(): void {
+    if (this.phase === "verifying") {
+      this.clearTimer();
+
+      logger.info({
+        message: "NetworkStatus: resume verification cancelled",
+        data: {
+          appState: this.appState,
+          snapshot: describeNetInfo(this.state.netInfo),
+          live: describeNetInfo(this.live),
+        },
+      });
+    }
+
+    this.phase = "frozen";
+  }
+
+  /**
+   * Opens the RESUME_VERIFICATION_DELAY_MS window. When it ends, compares the state published
+   * before background with the current live state, publishes the live state and bumps
+   * stillOfflineAfterResumeCount when the app is still offline.
+   */
+  private startVerification(): void {
+    this.phase = "verifying";
+
+    const snapshot = this.state.netInfo;
+    const startedAt = Date.now();
+
+    logger.info({
+      message: "NetworkStatus: resume verification started",
+      data: {
+        delayMs: RESUME_VERIFICATION_DELAY_MS,
+        appState: this.appState,
+        snapshot: describeNetInfo(snapshot),
+        live: describeNetInfo(this.live),
+      },
+    });
+
+    this.timer = setTimeout(() => {
+      this.timer = null;
+
+      if (this.phase !== "verifying") return;
+
+      const decision = getResumeDecision(
+        isOnline(snapshot) === true,
+        isOnline(this.live) === true
+      );
+
+      logger.info({
+        message: "NetworkStatus: resume verification finished",
+        data: {
+          decision,
+          elapsedMs: Date.now() - startedAt,
+          appState: this.appState,
+          snapshot: describeNetInfo(snapshot),
+          live: describeNetInfo(this.live),
+        },
+      });
+
+      this.phase = "live";
+
+      this.publish(
+        this.live,
+        this.state.stillOfflineAfterResumeCount +
+          (decision === "still_offline" ? 1 : 0)
+      );
+    }, RESUME_VERIFICATION_DELAY_MS);
+  }
+
+  /**
+   * Cancels the pending verification timer, if any.
+   */
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /**
+   * Replaces the snapshot and notifies subscribers; no-op when nothing changed.
+   * @param netInfo - NetInfo to publish
+   * @param stillOfflineAfterResumeCount - counter to publish, defaults to the current one
+   */
+  private publish(
+    netInfo: T,
+    stillOfflineAfterResumeCount = this.state.stillOfflineAfterResumeCount
+  ): void {
+    if (
+      netInfo === this.state.netInfo &&
+      stillOfflineAfterResumeCount === this.state.stillOfflineAfterResumeCount
+    ) {
+      return;
+    }
+
+    this.state = { netInfo, stillOfflineAfterResumeCount };
+    this.listeners.forEach((listener) => listener());
+  }
+}