@rocapine/expo-widget-activation 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @rocapine/expo-widget-activation
+
+Widget activation toolkit for Expo apps (iOS):
+
+- `getInstalledWidgets()` — WidgetKit `getCurrentConfigurations`; `[]` anywhere the bridge is absent.
+- `suspendApp()` — backgrounds the app (undocumented selector; accepted review risk; no-op off-iOS).
+- `isWidgetInstalled(widgets, kind)` — predicate helper.
+- `useWidgetDetection({ enabled, isTarget, onDetected })` — fires once the target widget appears on an app-foreground check.
+- `@rocapine/expo-widget-activation/video` — `TutorialVideo` (muted, loop, initialTime, playbackRate, PiP) + `videoProgress`. Requires `expo-video`.
+
+Install (git dep, dist committed):
+
+    "@rocapine/expo-widget-activation": "github:Rocapine/expo-widget-activation#v0.1.0"
+
+Autolinks as a standard Expo module — new native build required after install.

package/dist/index.d.mts

@@ -0,0 +1,21 @@
+interface InstalledWidget {
+    kind: string;
+    family: string;
+}
+declare function getInstalledWidgets(): Promise<InstalledWidget[]>;
+declare function suspendApp(): void;
+declare function isWidgetInstalled(widgets: InstalledWidget[], kind: string): boolean;
+interface UseWidgetDetectionOptions {
+    enabled: boolean;
+    /** Returns true when the target widget is present in the installed set. */
+    isTarget: (widgets: InstalledWidget[]) => boolean;
+    onDetected: () => void;
+}
+/**
+ * While enabled, re-checks WidgetKit configurations on every foreground
+ * transition (the user may background/foreground several times before
+ * managing to add the widget) and fires onDetected once isTarget matches.
+ */
+declare function useWidgetDetection({ enabled, isTarget, onDetected, }: UseWidgetDetectionOptions): void;
+
+export { type InstalledWidget, type UseWidgetDetectionOptions, getInstalledWidgets, isWidgetInstalled, suspendApp, useWidgetDetection };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+interface InstalledWidget {
+    kind: string;
+    family: string;
+}
+declare function getInstalledWidgets(): Promise<InstalledWidget[]>;
+declare function suspendApp(): void;
+declare function isWidgetInstalled(widgets: InstalledWidget[], kind: string): boolean;
+interface UseWidgetDetectionOptions {
+    enabled: boolean;
+    /** Returns true when the target widget is present in the installed set. */
+    isTarget: (widgets: InstalledWidget[]) => boolean;
+    onDetected: () => void;
+}
+/**
+ * While enabled, re-checks WidgetKit configurations on every foreground
+ * transition (the user may background/foreground several times before
+ * managing to add the widget) and fires onDetected once isTarget matches.
+ */
+declare function useWidgetDetection({ enabled, isTarget, onDetected, }: UseWidgetDetectionOptions): void;
+
+export { type InstalledWidget, type UseWidgetDetectionOptions, getInstalledWidgets, isWidgetInstalled, suspendApp, useWidgetDetection };

package/dist/index.js

@@ -0,0 +1,89 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getInstalledWidgets: () => getInstalledWidgets,
+  isWidgetInstalled: () => isWidgetInstalled,
+  suspendApp: () => suspendApp,
+  useWidgetDetection: () => useWidgetDetection
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_react_native = require("react-native");
+var import_expo_modules_core = require("expo-modules-core");
+var widgetCenterModule = null;
+if (import_react_native.Platform.OS === "ios") {
+  try {
+    widgetCenterModule = (0, import_expo_modules_core.requireNativeModule)("WidgetCenter");
+  } catch {
+    widgetCenterModule = null;
+  }
+}
+async function getInstalledWidgets() {
+  if (!widgetCenterModule) return [];
+  try {
+    return await widgetCenterModule.getInstalledWidgets();
+  } catch {
+    return [];
+  }
+}
+function suspendApp() {
+  widgetCenterModule?.suspendApp();
+}
+function isWidgetInstalled(widgets, kind) {
+  return widgets.some((widget) => widget.kind === kind);
+}
+function useWidgetDetection({
+  enabled,
+  isTarget,
+  onDetected
+}) {
+  (0, import_react.useEffect)(
+    function detectWidgetOnForeground() {
+      if (!enabled) return;
+      let cancelled = false;
+      async function check() {
+        const widgets = await getInstalledWidgets();
+        if (!cancelled && isTarget(widgets)) {
+          onDetected();
+        }
+      }
+      const subscription = import_react_native.AppState.addEventListener("change", (nextState) => {
+        if (nextState === "active") {
+          void check();
+        }
+      });
+      return () => {
+        cancelled = true;
+        subscription.remove();
+      };
+    },
+    [enabled, isTarget, onDetected]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getInstalledWidgets,
+  isWidgetInstalled,
+  suspendApp,
+  useWidgetDetection
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { AppState, Platform } from \"react-native\";\nimport { requireNativeModule } from \"expo-modules-core\";\n\nexport interface InstalledWidget {\n  kind: string;\n  family: string;\n}\n\ninterface WidgetCenterModuleType {\n  getInstalledWidgets(): Promise<InstalledWidget[]>;\n  suspendApp(): void;\n}\n\nlet widgetCenterModule: WidgetCenterModuleType | null = null;\n\nif (Platform.OS === \"ios\") {\n  try {\n    // Jest and other non-native environments can report iOS without the bridge linked.\n    widgetCenterModule =\n      requireNativeModule<WidgetCenterModuleType>(\"WidgetCenter\");\n  } catch {\n    widgetCenterModule = null;\n  }\n}\n\nexport async function getInstalledWidgets(): Promise<InstalledWidget[]> {\n  if (!widgetCenterModule) return [];\n  try {\n    return await widgetCenterModule.getInstalledWidgets();\n  } catch {\n    // Treat \"can't read configurations\" as \"not installed\": callers always\n    // keep a manual path available.\n    return [];\n  }\n}\n\nexport function suspendApp(): void {\n  widgetCenterModule?.suspendApp();\n}\n\nexport function isWidgetInstalled(\n  widgets: InstalledWidget[],\n  kind: string\n): boolean {\n  return widgets.some((widget) => widget.kind === kind);\n}\n\nexport interface UseWidgetDetectionOptions {\n  enabled: boolean;\n  /** Returns true when the target widget is present in the installed set. */\n  isTarget: (widgets: InstalledWidget[]) => boolean;\n  onDetected: () => void;\n}\n\n/**\n * While enabled, re-checks WidgetKit configurations on every foreground\n * transition (the user may background/foreground several times before\n * managing to add the widget) and fires onDetected once isTarget matches.\n */\nexport function useWidgetDetection({\n  enabled,\n  isTarget,\n  onDetected,\n}: UseWidgetDetectionOptions) {\n  useEffect(\n    function detectWidgetOnForeground() {\n      if (!enabled) return;\n\n      let cancelled = false;\n\n      async function check() {\n        const widgets = await getInstalledWidgets();\n        if (!cancelled && isTarget(widgets)) {\n          onDetected();\n        }\n      }\n\n      const subscription = AppState.addEventListener(\"change\", (nextState) => {\n        if (nextState === \"active\") {\n          void check();\n        }\n      });\n\n      return () => {\n        cancelled = true;\n        subscription.remove();\n      };\n    },\n    [enabled, isTarget, onDetected]\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA0B;AAC1B,0BAAmC;AACnC,+BAAoC;AAYpC,IAAI,qBAAoD;AAExD,IAAI,6BAAS,OAAO,OAAO;AACzB,MAAI;AAEF,6BACE,8CAA4C,cAAc;AAAA,EAC9D,QAAQ;AACN,yBAAqB;AAAA,EACvB;AACF;AAEA,eAAsB,sBAAkD;AACtE,MAAI,CAAC,mBAAoB,QAAO,CAAC;AACjC,MAAI;AACF,WAAO,MAAM,mBAAmB,oBAAoB;AAAA,EACtD,QAAQ;AAGN,WAAO,CAAC;AAAA,EACV;AACF;AAEO,SAAS,aAAmB;AACjC,sBAAoB,WAAW;AACjC;AAEO,SAAS,kBACd,SACA,MACS;AACT,SAAO,QAAQ,KAAK,CAAC,WAAW,OAAO,SAAS,IAAI;AACtD;AAcO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF,GAA8B;AAC5B;AAAA,IACE,SAAS,2BAA2B;AAClC,UAAI,CAAC,QAAS;AAEd,UAAI,YAAY;AAEhB,qBAAe,QAAQ;AACrB,cAAM,UAAU,MAAM,oBAAoB;AAC1C,YAAI,CAAC,aAAa,SAAS,OAAO,GAAG;AACnC,qBAAW;AAAA,QACb;AAAA,MACF;AAEA,YAAM,eAAe,6BAAS,iBAAiB,UAAU,CAAC,cAAc;AACtE,YAAI,cAAc,UAAU;AAC1B,eAAK,MAAM;AAAA,QACb;AAAA,MACF,CAAC;AAED,aAAO,MAAM;AACX,oBAAY;AACZ,qBAAa,OAAO;AAAA,MACtB;AAAA,IACF;AAAA,IACA,CAAC,SAAS,UAAU,UAAU;AAAA,EAChC;AACF;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,61 @@
+// src/index.ts
+import { useEffect } from "react";
+import { AppState, Platform } from "react-native";
+import { requireNativeModule } from "expo-modules-core";
+var widgetCenterModule = null;
+if (Platform.OS === "ios") {
+  try {
+    widgetCenterModule = requireNativeModule("WidgetCenter");
+  } catch {
+    widgetCenterModule = null;
+  }
+}
+async function getInstalledWidgets() {
+  if (!widgetCenterModule) return [];
+  try {
+    return await widgetCenterModule.getInstalledWidgets();
+  } catch {
+    return [];
+  }
+}
+function suspendApp() {
+  widgetCenterModule?.suspendApp();
+}
+function isWidgetInstalled(widgets, kind) {
+  return widgets.some((widget) => widget.kind === kind);
+}
+function useWidgetDetection({
+  enabled,
+  isTarget,
+  onDetected
+}) {
+  useEffect(
+    function detectWidgetOnForeground() {
+      if (!enabled) return;
+      let cancelled = false;
+      async function check() {
+        const widgets = await getInstalledWidgets();
+        if (!cancelled && isTarget(widgets)) {
+          onDetected();
+        }
+      }
+      const subscription = AppState.addEventListener("change", (nextState) => {
+        if (nextState === "active") {
+          void check();
+        }
+      });
+      return () => {
+        cancelled = true;
+        subscription.remove();
+      };
+    },
+    [enabled, isTarget, onDetected]
+  );
+}
+export {
+  getInstalledWidgets,
+  isWidgetInstalled,
+  suspendApp,
+  useWidgetDetection
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { AppState, Platform } from \"react-native\";\nimport { requireNativeModule } from \"expo-modules-core\";\n\nexport interface InstalledWidget {\n  kind: string;\n  family: string;\n}\n\ninterface WidgetCenterModuleType {\n  getInstalledWidgets(): Promise<InstalledWidget[]>;\n  suspendApp(): void;\n}\n\nlet widgetCenterModule: WidgetCenterModuleType | null = null;\n\nif (Platform.OS === \"ios\") {\n  try {\n    // Jest and other non-native environments can report iOS without the bridge linked.\n    widgetCenterModule =\n      requireNativeModule<WidgetCenterModuleType>(\"WidgetCenter\");\n  } catch {\n    widgetCenterModule = null;\n  }\n}\n\nexport async function getInstalledWidgets(): Promise<InstalledWidget[]> {\n  if (!widgetCenterModule) return [];\n  try {\n    return await widgetCenterModule.getInstalledWidgets();\n  } catch {\n    // Treat \"can't read configurations\" as \"not installed\": callers always\n    // keep a manual path available.\n    return [];\n  }\n}\n\nexport function suspendApp(): void {\n  widgetCenterModule?.suspendApp();\n}\n\nexport function isWidgetInstalled(\n  widgets: InstalledWidget[],\n  kind: string\n): boolean {\n  return widgets.some((widget) => widget.kind === kind);\n}\n\nexport interface UseWidgetDetectionOptions {\n  enabled: boolean;\n  /** Returns true when the target widget is present in the installed set. */\n  isTarget: (widgets: InstalledWidget[]) => boolean;\n  onDetected: () => void;\n}\n\n/**\n * While enabled, re-checks WidgetKit configurations on every foreground\n * transition (the user may background/foreground several times before\n * managing to add the widget) and fires onDetected once isTarget matches.\n */\nexport function useWidgetDetection({\n  enabled,\n  isTarget,\n  onDetected,\n}: UseWidgetDetectionOptions) {\n  useEffect(\n    function detectWidgetOnForeground() {\n      if (!enabled) return;\n\n      let cancelled = false;\n\n      async function check() {\n        const widgets = await getInstalledWidgets();\n        if (!cancelled && isTarget(widgets)) {\n          onDetected();\n        }\n      }\n\n      const subscription = AppState.addEventListener(\"change\", (nextState) => {\n        if (nextState === \"active\") {\n          void check();\n        }\n      });\n\n      return () => {\n        cancelled = true;\n        subscription.remove();\n      };\n    },\n    [enabled, isTarget, onDetected]\n  );\n}\n"],"mappings":";AAAA,SAAS,iBAAiB;AAC1B,SAAS,UAAU,gBAAgB;AACnC,SAAS,2BAA2B;AAYpC,IAAI,qBAAoD;AAExD,IAAI,SAAS,OAAO,OAAO;AACzB,MAAI;AAEF,yBACE,oBAA4C,cAAc;AAAA,EAC9D,QAAQ;AACN,yBAAqB;AAAA,EACvB;AACF;AAEA,eAAsB,sBAAkD;AACtE,MAAI,CAAC,mBAAoB,QAAO,CAAC;AACjC,MAAI;AACF,WAAO,MAAM,mBAAmB,oBAAoB;AAAA,EACtD,QAAQ;AAGN,WAAO,CAAC;AAAA,EACV;AACF;AAEO,SAAS,aAAmB;AACjC,sBAAoB,WAAW;AACjC;AAEO,SAAS,kBACd,SACA,MACS;AACT,SAAO,QAAQ,KAAK,CAAC,WAAW,OAAO,SAAS,IAAI;AACtD;AAcO,SAAS,mBAAmB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF,GAA8B;AAC5B;AAAA,IACE,SAAS,2BAA2B;AAClC,UAAI,CAAC,QAAS;AAEd,UAAI,YAAY;AAEhB,qBAAe,QAAQ;AACrB,cAAM,UAAU,MAAM,oBAAoB;AAC1C,YAAI,CAAC,aAAa,SAAS,OAAO,GAAG;AACnC,qBAAW;AAAA,QACb;AAAA,MACF;AAEA,YAAM,eAAe,SAAS,iBAAiB,UAAU,CAAC,cAAc;AACtE,YAAI,cAAc,UAAU;AAC1B,eAAK,MAAM;AAAA,QACb;AAAA,MACF,CAAC;AAED,aAAO,MAAM;AACX,oBAAY;AACZ,qBAAa,OAAO;AAAA,MACtB;AAAA,IACF;AAAA,IACA,CAAC,SAAS,UAAU,UAAU;AAAA,EAChC;AACF;","names":[]}

package/dist/video.d.mts

@@ -0,0 +1,33 @@
+import * as react from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+
+/** Playback position mapped over the played range [initialTime, duration] to 0..1, clamped. */
+declare function videoProgress(currentTime: number, initialTime: number, duration: number): number;
+interface TutorialVideoHandle {
+    startPictureInPicture: () => Promise<void>;
+}
+interface TutorialVideoProps {
+    source: number;
+    /** Start position in seconds (e.g. skip the part covered by a previous step). */
+    initialTime?: number;
+    /** Playback speed multiplier (default 1). */
+    playbackRate?: number;
+    pipEnabled?: boolean;
+    /** Loop playback. Mutually exclusive with onEnded (a looping video never completes). */
+    loop?: boolean;
+    style?: StyleProp<ViewStyle>;
+    /** Reports playback position as 0..1 over the played range. */
+    onProgress?: (progress: number) => void;
+    /** Fires when playback reaches the end (loop off). */
+    onEnded?: () => void;
+}
+/**
+ * Muted tutorial player. It never pauses on backgrounding
+ * (staysActiveInBackground) so it has always progressed when the user comes
+ * back. With pipEnabled it detaches into PiP automatically when the app
+ * backgrounds (or programmatically via the handle); while in PiP the video
+ * loops over the full how-to, and playback resumes on screen when PiP ends.
+ */
+declare const TutorialVideo: react.ForwardRefExoticComponent<TutorialVideoProps & react.RefAttributes<TutorialVideoHandle>>;
+
+export { TutorialVideo, type TutorialVideoHandle, type TutorialVideoProps, videoProgress };

package/dist/video.d.ts

@@ -0,0 +1,33 @@
+import * as react from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+
+/** Playback position mapped over the played range [initialTime, duration] to 0..1, clamped. */
+declare function videoProgress(currentTime: number, initialTime: number, duration: number): number;
+interface TutorialVideoHandle {
+    startPictureInPicture: () => Promise<void>;
+}
+interface TutorialVideoProps {
+    source: number;
+    /** Start position in seconds (e.g. skip the part covered by a previous step). */
+    initialTime?: number;
+    /** Playback speed multiplier (default 1). */
+    playbackRate?: number;
+    pipEnabled?: boolean;
+    /** Loop playback. Mutually exclusive with onEnded (a looping video never completes). */
+    loop?: boolean;
+    style?: StyleProp<ViewStyle>;
+    /** Reports playback position as 0..1 over the played range. */
+    onProgress?: (progress: number) => void;
+    /** Fires when playback reaches the end (loop off). */
+    onEnded?: () => void;
+}
+/**
+ * Muted tutorial player. It never pauses on backgrounding
+ * (staysActiveInBackground) so it has always progressed when the user comes
+ * back. With pipEnabled it detaches into PiP automatically when the app
+ * backgrounds (or programmatically via the handle); while in PiP the video
+ * loops over the full how-to, and playback resumes on screen when PiP ends.
+ */
+declare const TutorialVideo: react.ForwardRefExoticComponent<TutorialVideoProps & react.RefAttributes<TutorialVideoHandle>>;
+
+export { TutorialVideo, type TutorialVideoHandle, type TutorialVideoProps, videoProgress };

package/dist/video.js

@@ -0,0 +1,108 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/video.tsx
+var video_exports = {};
+__export(video_exports, {
+  TutorialVideo: () => TutorialVideo,
+  videoProgress: () => videoProgress
+});
+module.exports = __toCommonJS(video_exports);
+var import_expo = require("expo");
+var import_expo_video = require("expo-video");
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function videoProgress(currentTime, initialTime, duration) {
+  if (duration <= 0 || duration <= initialTime) return 0;
+  const progress = (currentTime - initialTime) / (duration - initialTime);
+  return Math.max(0, Math.min(1, progress));
+}
+var TutorialVideo = (0, import_react.forwardRef)(function TutorialVideo2({
+  source,
+  initialTime,
+  playbackRate = 1,
+  pipEnabled = false,
+  loop = false,
+  style,
+  onProgress,
+  onEnded
+}, ref) {
+  const videoViewRef = (0, import_react.useRef)(null);
+  const player = (0, import_expo_video.useVideoPlayer)(source, (player2) => {
+    player2.loop = loop;
+    player2.muted = true;
+    player2.staysActiveInBackground = true;
+    player2.playbackRate = playbackRate;
+    player2.timeUpdateEventInterval = 0.1;
+    if (initialTime !== void 0) {
+      player2.currentTime = initialTime;
+    }
+    player2.play();
+  });
+  const initialTimeValue = initialTime ?? 0;
+  (0, import_expo.useEventListener)(player, "timeUpdate", ({ currentTime }) => {
+    onProgress?.(videoProgress(currentTime, initialTimeValue, player.duration));
+  });
+  (0, import_expo.useEventListener)(player, "playToEnd", () => {
+    if (player.loop) return;
+    onEnded?.();
+  });
+  (0, import_react.useImperativeHandle)(
+    ref,
+    () => ({
+      startPictureInPicture: async () => {
+        try {
+          await videoViewRef.current?.startPictureInPicture();
+        } catch {
+        }
+      }
+    }),
+    []
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    import_expo_video.VideoView,
+    {
+      style: style ?? { flex: 1 },
+      ref: videoViewRef,
+      player,
+      nativeControls: false,
+      contentFit: "cover",
+      allowsPictureInPicture: pipEnabled,
+      startsPictureInPictureAutomatically: pipEnabled,
+      allowsVideoFrameAnalysis: false,
+      onPictureInPictureStart: () => {
+        if (player.duration > 0 && player.currentTime >= player.duration - 0.1) {
+          player.currentTime = 0;
+        }
+        player.loop = true;
+        player.play();
+      },
+      onPictureInPictureStop: () => {
+        player.loop = loop;
+        player.play();
+      }
+    }
+  );
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TutorialVideo,
+  videoProgress
+});
+//# sourceMappingURL=video.js.map

package/dist/video.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/video.tsx"],"sourcesContent":["import { useEventListener } from \"expo\";\nimport { useVideoPlayer, VideoView } from \"expo-video\";\nimport { forwardRef, useImperativeHandle, useRef } from \"react\";\nimport type { StyleProp, ViewStyle } from \"react-native\";\n\n/** Playback position mapped over the played range [initialTime, duration] to 0..1, clamped. */\nexport function videoProgress(\n  currentTime: number,\n  initialTime: number,\n  duration: number\n): number {\n  if (duration <= 0 || duration <= initialTime) return 0;\n  const progress = (currentTime - initialTime) / (duration - initialTime);\n  return Math.max(0, Math.min(1, progress));\n}\n\nexport interface TutorialVideoHandle {\n  startPictureInPicture: () => Promise<void>;\n}\n\nexport interface TutorialVideoProps {\n  source: number; // require()d asset\n  /** Start position in seconds (e.g. skip the part covered by a previous step). */\n  initialTime?: number;\n  /** Playback speed multiplier (default 1). */\n  playbackRate?: number;\n  pipEnabled?: boolean;\n  /** Loop playback. Mutually exclusive with onEnded (a looping video never completes). */\n  loop?: boolean;\n  style?: StyleProp<ViewStyle>;\n  /** Reports playback position as 0..1 over the played range. */\n  onProgress?: (progress: number) => void;\n  /** Fires when playback reaches the end (loop off). */\n  onEnded?: () => void;\n}\n\n/**\n * Muted tutorial player. It never pauses on backgrounding\n * (staysActiveInBackground) so it has always progressed when the user comes\n * back. With pipEnabled it detaches into PiP automatically when the app\n * backgrounds (or programmatically via the handle); while in PiP the video\n * loops over the full how-to, and playback resumes on screen when PiP ends.\n */\nexport const TutorialVideo = forwardRef<\n  TutorialVideoHandle,\n  TutorialVideoProps\n>(function TutorialVideo(\n  {\n    source,\n    initialTime,\n    playbackRate = 1,\n    pipEnabled = false,\n    loop = false,\n    style,\n    onProgress,\n    onEnded,\n  },\n  ref\n) {\n  const videoViewRef = useRef<VideoView>(null);\n\n  const player = useVideoPlayer(source, (player) => {\n    player.loop = loop;\n    player.muted = true;\n    player.staysActiveInBackground = true;\n    player.playbackRate = playbackRate;\n    player.timeUpdateEventInterval = 0.1;\n    if (initialTime !== undefined) {\n      player.currentTime = initialTime;\n    }\n    player.play();\n  });\n\n  const initialTimeValue = initialTime ?? 0;\n\n  useEventListener(player, \"timeUpdate\", ({ currentTime }) => {\n    onProgress?.(videoProgress(currentTime, initialTimeValue, player.duration));\n  });\n\n  useEventListener(player, \"playToEnd\", () => {\n    // expo-video emits playToEnd on every loop iteration (it emits before\n    // seeking back to zero). While looping — i.e. detached into PiP with the\n    // app backgrounded — an end event is not a completion: reporting it\n    // would tear down the UI out from under the user. Only report ends of\n    // the on-screen, loop-off pass.\n    if (player.loop) return;\n    onEnded?.();\n  });\n\n  useImperativeHandle(\n    ref,\n    () => ({\n      startPictureInPicture: async () => {\n        try {\n          await videoViewRef.current?.startPictureInPicture();\n        } catch {\n          // PiP unavailable (device/setting): the flow continues without it.\n        }\n      },\n    }),\n    []\n  );\n\n  return (\n    <VideoView\n      style={style ?? { flex: 1 }}\n      ref={videoViewRef}\n      player={player}\n      nativeControls={false}\n      contentFit=\"cover\"\n      allowsPictureInPicture={pipEnabled}\n      startsPictureInPictureAutomatically={pipEnabled}\n      allowsVideoFrameAnalysis={false}\n      onPictureInPictureStart={() => {\n        // In the floating window the full how-to loops continuously. If the\n        // on-screen playback had already finished (loop is off there), a\n        // stale `loop = true` won't restart an ended player — rewind first.\n        if (\n          player.duration > 0 &&\n          player.currentTime >= player.duration - 0.1\n        ) {\n          player.currentTime = 0;\n        }\n        player.loop = true;\n        player.play();\n      }}\n      onPictureInPictureStop={() => {\n        player.loop = loop;\n        player.play();\n      }}\n    />\n  );\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAiC;AACjC,wBAA0C;AAC1C,mBAAwD;AAsGpD;AAlGG,SAAS,cACd,aACA,aACA,UACQ;AACR,MAAI,YAAY,KAAK,YAAY,YAAa,QAAO;AACrD,QAAM,YAAY,cAAc,gBAAgB,WAAW;AAC3D,SAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC;AAC1C;AA6BO,IAAM,oBAAgB,yBAG3B,SAASA,eACT;AAAA,EACE;AAAA,EACA;AAAA,EACA,eAAe;AAAA,EACf,aAAa;AAAA,EACb,OAAO;AAAA,EACP;AAAA,EACA;AAAA,EACA;AACF,GACA,KACA;AACA,QAAM,mBAAe,qBAAkB,IAAI;AAE3C,QAAM,aAAS,kCAAe,QAAQ,CAACC,YAAW;AAChD,IAAAA,QAAO,OAAO;AACd,IAAAA,QAAO,QAAQ;AACf,IAAAA,QAAO,0BAA0B;AACjC,IAAAA,QAAO,eAAe;AACtB,IAAAA,QAAO,0BAA0B;AACjC,QAAI,gBAAgB,QAAW;AAC7B,MAAAA,QAAO,cAAc;AAAA,IACvB;AACA,IAAAA,QAAO,KAAK;AAAA,EACd,CAAC;AAED,QAAM,mBAAmB,eAAe;AAExC,oCAAiB,QAAQ,cAAc,CAAC,EAAE,YAAY,MAAM;AAC1D,iBAAa,cAAc,aAAa,kBAAkB,OAAO,QAAQ,CAAC;AAAA,EAC5E,CAAC;AAED,oCAAiB,QAAQ,aAAa,MAAM;AAM1C,QAAI,OAAO,KAAM;AACjB,cAAU;AAAA,EACZ,CAAC;AAED;AAAA,IACE;AAAA,IACA,OAAO;AAAA,MACL,uBAAuB,YAAY;AACjC,YAAI;AACF,gBAAM,aAAa,SAAS,sBAAsB;AAAA,QACpD,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,IACA,CAAC;AAAA,EACH;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,OAAO,SAAS,EAAE,MAAM,EAAE;AAAA,MAC1B,KAAK;AAAA,MACL;AAAA,MACA,gBAAgB;AAAA,MAChB,YAAW;AAAA,MACX,wBAAwB;AAAA,MACxB,qCAAqC;AAAA,MACrC,0BAA0B;AAAA,MAC1B,yBAAyB,MAAM;AAI7B,YACE,OAAO,WAAW,KAClB,OAAO,eAAe,OAAO,WAAW,KACxC;AACA,iBAAO,cAAc;AAAA,QACvB;AACA,eAAO,OAAO;AACd,eAAO,KAAK;AAAA,MACd;AAAA,MACA,wBAAwB,MAAM;AAC5B,eAAO,OAAO;AACd,eAAO,KAAK;AAAA,MACd;AAAA;AAAA,EACF;AAEJ,CAAC;","names":["TutorialVideo","player"]}

package/dist/video.mjs

@@ -0,0 +1,82 @@
+// src/video.tsx
+import { useEventListener } from "expo";
+import { useVideoPlayer, VideoView } from "expo-video";
+import { forwardRef, useImperativeHandle, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+function videoProgress(currentTime, initialTime, duration) {
+  if (duration <= 0 || duration <= initialTime) return 0;
+  const progress = (currentTime - initialTime) / (duration - initialTime);
+  return Math.max(0, Math.min(1, progress));
+}
+var TutorialVideo = forwardRef(function TutorialVideo2({
+  source,
+  initialTime,
+  playbackRate = 1,
+  pipEnabled = false,
+  loop = false,
+  style,
+  onProgress,
+  onEnded
+}, ref) {
+  const videoViewRef = useRef(null);
+  const player = useVideoPlayer(source, (player2) => {
+    player2.loop = loop;
+    player2.muted = true;
+    player2.staysActiveInBackground = true;
+    player2.playbackRate = playbackRate;
+    player2.timeUpdateEventInterval = 0.1;
+    if (initialTime !== void 0) {
+      player2.currentTime = initialTime;
+    }
+    player2.play();
+  });
+  const initialTimeValue = initialTime ?? 0;
+  useEventListener(player, "timeUpdate", ({ currentTime }) => {
+    onProgress?.(videoProgress(currentTime, initialTimeValue, player.duration));
+  });
+  useEventListener(player, "playToEnd", () => {
+    if (player.loop) return;
+    onEnded?.();
+  });
+  useImperativeHandle(
+    ref,
+    () => ({
+      startPictureInPicture: async () => {
+        try {
+          await videoViewRef.current?.startPictureInPicture();
+        } catch {
+        }
+      }
+    }),
+    []
+  );
+  return /* @__PURE__ */ jsx(
+    VideoView,
+    {
+      style: style ?? { flex: 1 },
+      ref: videoViewRef,
+      player,
+      nativeControls: false,
+      contentFit: "cover",
+      allowsPictureInPicture: pipEnabled,
+      startsPictureInPictureAutomatically: pipEnabled,
+      allowsVideoFrameAnalysis: false,
+      onPictureInPictureStart: () => {
+        if (player.duration > 0 && player.currentTime >= player.duration - 0.1) {
+          player.currentTime = 0;
+        }
+        player.loop = true;
+        player.play();
+      },
+      onPictureInPictureStop: () => {
+        player.loop = loop;
+        player.play();
+      }
+    }
+  );
+});
+export {
+  TutorialVideo,
+  videoProgress
+};
+//# sourceMappingURL=video.mjs.map

package/dist/video.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/video.tsx"],"sourcesContent":["import { useEventListener } from \"expo\";\nimport { useVideoPlayer, VideoView } from \"expo-video\";\nimport { forwardRef, useImperativeHandle, useRef } from \"react\";\nimport type { StyleProp, ViewStyle } from \"react-native\";\n\n/** Playback position mapped over the played range [initialTime, duration] to 0..1, clamped. */\nexport function videoProgress(\n  currentTime: number,\n  initialTime: number,\n  duration: number\n): number {\n  if (duration <= 0 || duration <= initialTime) return 0;\n  const progress = (currentTime - initialTime) / (duration - initialTime);\n  return Math.max(0, Math.min(1, progress));\n}\n\nexport interface TutorialVideoHandle {\n  startPictureInPicture: () => Promise<void>;\n}\n\nexport interface TutorialVideoProps {\n  source: number; // require()d asset\n  /** Start position in seconds (e.g. skip the part covered by a previous step). */\n  initialTime?: number;\n  /** Playback speed multiplier (default 1). */\n  playbackRate?: number;\n  pipEnabled?: boolean;\n  /** Loop playback. Mutually exclusive with onEnded (a looping video never completes). */\n  loop?: boolean;\n  style?: StyleProp<ViewStyle>;\n  /** Reports playback position as 0..1 over the played range. */\n  onProgress?: (progress: number) => void;\n  /** Fires when playback reaches the end (loop off). */\n  onEnded?: () => void;\n}\n\n/**\n * Muted tutorial player. It never pauses on backgrounding\n * (staysActiveInBackground) so it has always progressed when the user comes\n * back. With pipEnabled it detaches into PiP automatically when the app\n * backgrounds (or programmatically via the handle); while in PiP the video\n * loops over the full how-to, and playback resumes on screen when PiP ends.\n */\nexport const TutorialVideo = forwardRef<\n  TutorialVideoHandle,\n  TutorialVideoProps\n>(function TutorialVideo(\n  {\n    source,\n    initialTime,\n    playbackRate = 1,\n    pipEnabled = false,\n    loop = false,\n    style,\n    onProgress,\n    onEnded,\n  },\n  ref\n) {\n  const videoViewRef = useRef<VideoView>(null);\n\n  const player = useVideoPlayer(source, (player) => {\n    player.loop = loop;\n    player.muted = true;\n    player.staysActiveInBackground = true;\n    player.playbackRate = playbackRate;\n    player.timeUpdateEventInterval = 0.1;\n    if (initialTime !== undefined) {\n      player.currentTime = initialTime;\n    }\n    player.play();\n  });\n\n  const initialTimeValue = initialTime ?? 0;\n\n  useEventListener(player, \"timeUpdate\", ({ currentTime }) => {\n    onProgress?.(videoProgress(currentTime, initialTimeValue, player.duration));\n  });\n\n  useEventListener(player, \"playToEnd\", () => {\n    // expo-video emits playToEnd on every loop iteration (it emits before\n    // seeking back to zero). While looping — i.e. detached into PiP with the\n    // app backgrounded — an end event is not a completion: reporting it\n    // would tear down the UI out from under the user. Only report ends of\n    // the on-screen, loop-off pass.\n    if (player.loop) return;\n    onEnded?.();\n  });\n\n  useImperativeHandle(\n    ref,\n    () => ({\n      startPictureInPicture: async () => {\n        try {\n          await videoViewRef.current?.startPictureInPicture();\n        } catch {\n          // PiP unavailable (device/setting): the flow continues without it.\n        }\n      },\n    }),\n    []\n  );\n\n  return (\n    <VideoView\n      style={style ?? { flex: 1 }}\n      ref={videoViewRef}\n      player={player}\n      nativeControls={false}\n      contentFit=\"cover\"\n      allowsPictureInPicture={pipEnabled}\n      startsPictureInPictureAutomatically={pipEnabled}\n      allowsVideoFrameAnalysis={false}\n      onPictureInPictureStart={() => {\n        // In the floating window the full how-to loops continuously. If the\n        // on-screen playback had already finished (loop is off there), a\n        // stale `loop = true` won't restart an ended player — rewind first.\n        if (\n          player.duration > 0 &&\n          player.currentTime >= player.duration - 0.1\n        ) {\n          player.currentTime = 0;\n        }\n        player.loop = true;\n        player.play();\n      }}\n      onPictureInPictureStop={() => {\n        player.loop = loop;\n        player.play();\n      }}\n    />\n  );\n});\n"],"mappings":";AAAA,SAAS,wBAAwB;AACjC,SAAS,gBAAgB,iBAAiB;AAC1C,SAAS,YAAY,qBAAqB,cAAc;AAsGpD;AAlGG,SAAS,cACd,aACA,aACA,UACQ;AACR,MAAI,YAAY,KAAK,YAAY,YAAa,QAAO;AACrD,QAAM,YAAY,cAAc,gBAAgB,WAAW;AAC3D,SAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC;AAC1C;AA6BO,IAAM,gBAAgB,WAG3B,SAASA,eACT;AAAA,EACE;AAAA,EACA;AAAA,EACA,eAAe;AAAA,EACf,aAAa;AAAA,EACb,OAAO;AAAA,EACP;AAAA,EACA;AAAA,EACA;AACF,GACA,KACA;AACA,QAAM,eAAe,OAAkB,IAAI;AAE3C,QAAM,SAAS,eAAe,QAAQ,CAACC,YAAW;AAChD,IAAAA,QAAO,OAAO;AACd,IAAAA,QAAO,QAAQ;AACf,IAAAA,QAAO,0BAA0B;AACjC,IAAAA,QAAO,eAAe;AACtB,IAAAA,QAAO,0BAA0B;AACjC,QAAI,gBAAgB,QAAW;AAC7B,MAAAA,QAAO,cAAc;AAAA,IACvB;AACA,IAAAA,QAAO,KAAK;AAAA,EACd,CAAC;AAED,QAAM,mBAAmB,eAAe;AAExC,mBAAiB,QAAQ,cAAc,CAAC,EAAE,YAAY,MAAM;AAC1D,iBAAa,cAAc,aAAa,kBAAkB,OAAO,QAAQ,CAAC;AAAA,EAC5E,CAAC;AAED,mBAAiB,QAAQ,aAAa,MAAM;AAM1C,QAAI,OAAO,KAAM;AACjB,cAAU;AAAA,EACZ,CAAC;AAED;AAAA,IACE;AAAA,IACA,OAAO;AAAA,MACL,uBAAuB,YAAY;AACjC,YAAI;AACF,gBAAM,aAAa,SAAS,sBAAsB;AAAA,QACpD,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,IACA,CAAC;AAAA,EACH;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,OAAO,SAAS,EAAE,MAAM,EAAE;AAAA,MAC1B,KAAK;AAAA,MACL;AAAA,MACA,gBAAgB;AAAA,MAChB,YAAW;AAAA,MACX,wBAAwB;AAAA,MACxB,qCAAqC;AAAA,MACrC,0BAA0B;AAAA,MAC1B,yBAAyB,MAAM;AAI7B,YACE,OAAO,WAAW,KAClB,OAAO,eAAe,OAAO,WAAW,KACxC;AACA,iBAAO,cAAc;AAAA,QACvB;AACA,eAAO,OAAO;AACd,eAAO,KAAK;AAAA,MACd;AAAA,MACA,wBAAwB,MAAM;AAC5B,eAAO,OAAO;AACd,eAAO,KAAK;AAAA,MACd;AAAA;AAAA,EACF;AAEJ,CAAC;","names":["TutorialVideo","player"]}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["ios"],
+  "ios": {
+    "modules": ["WidgetCenterModule"]
+  }
+}

package/ios/RocapineWidgetActivation.podspec

@@ -0,0 +1,20 @@
+Pod::Spec.new do |s|
+  s.name           = 'RocapineWidgetActivation'
+  s.version        = '0.1.0'
+  s.summary        = 'Read WidgetKit configurations and suspend the app'
+  s.description    = 'Expo module exposing WidgetCenter.getCurrentConfigurations and an app-suspend helper for widget activation flows'
+  s.author         = 'Rocapine'
+  s.homepage       = 'https://github.com/Rocapine/expo-widget-activation'
+  s.platform       = :ios, '15.1'
+  s.source         = { git: 'https://github.com/Rocapine/expo-widget-activation.git' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/WidgetCenterModule.swift

@@ -0,0 +1,32 @@
+import ExpoModulesCore
+import WidgetKit
+import UIKit
+
+public class WidgetCenterModule: Module {
+    public func definition() -> ModuleDefinition {
+        Name("WidgetCenter")
+
+        AsyncFunction("getInstalledWidgets") { (promise: Promise) in
+            WidgetCenter.shared.getCurrentConfigurations { result in
+                switch result {
+                case .success(let infos):
+                    let widgets = infos.map { info -> [String: String] in
+                        ["kind": info.kind, "family": String(describing: info.family)]
+                    }
+                    promise.resolve(widgets)
+                case .failure(let error):
+                    promise.reject("WIDGET_CENTER_ERROR", error.localizedDescription)
+                }
+            }
+        }
+
+        Function("suspendApp") {
+            DispatchQueue.main.async {
+                // No public API exists to background an app. `suspend` is an
+                // undocumented UIApplication selector (accepted review risk).
+                // The UX degrades gracefully if this call is removed.
+                UIApplication.shared.perform(#selector(NSXPCConnection.suspend))
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@rocapine/expo-widget-activation",
+  "version": "0.1.0",
+  "description": "Widget activation toolkit for Expo apps: WidgetKit installed-widget detection, app suspend, foreground detection hook, and a muted looping tutorial video player with PiP.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rocapine/expo-widget-activation.git"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "import": "./dist/video.mjs",
+      "require": "./dist/video.js"
+    },
+    "./expo-module.config.json": "./expo-module.config.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "ios",
+    "expo-module.config.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "type": "tsc --noEmit",
+    "test": "jest",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-modules-core": "*",
+    "expo-video": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo-video": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/react": "*",
+    "@types/react-test-renderer": "^19.1.0",
+    "expo": "^57.0.4",
+    "expo-modules-core": "^2.0.0",
+    "expo-video": "^57.0.0",
+    "jest": "^29.7.0",
+    "react": "^19.0.0",
+    "react-native": "^0.86.0",
+    "react-test-renderer": "^19.0.0",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+import { useEffect } from "react";
+import { AppState, Platform } from "react-native";
+import { requireNativeModule } from "expo-modules-core";
+
+export interface InstalledWidget {
+  kind: string;
+  family: string;
+}
+
+interface WidgetCenterModuleType {
+  getInstalledWidgets(): Promise<InstalledWidget[]>;
+  suspendApp(): void;
+}
+
+let widgetCenterModule: WidgetCenterModuleType | null = null;
+
+if (Platform.OS === "ios") {
+  try {
+    // Jest and other non-native environments can report iOS without the bridge linked.
+    widgetCenterModule =
+      requireNativeModule<WidgetCenterModuleType>("WidgetCenter");
+  } catch {
+    widgetCenterModule = null;
+  }
+}
+
+export async function getInstalledWidgets(): Promise<InstalledWidget[]> {
+  if (!widgetCenterModule) return [];
+  try {
+    return await widgetCenterModule.getInstalledWidgets();
+  } catch {
+    // Treat "can't read configurations" as "not installed": callers always
+    // keep a manual path available.
+    return [];
+  }
+}
+
+export function suspendApp(): void {
+  widgetCenterModule?.suspendApp();
+}
+
+export function isWidgetInstalled(
+  widgets: InstalledWidget[],
+  kind: string
+): boolean {
+  return widgets.some((widget) => widget.kind === kind);
+}
+
+export interface UseWidgetDetectionOptions {
+  enabled: boolean;
+  /** Returns true when the target widget is present in the installed set. */
+  isTarget: (widgets: InstalledWidget[]) => boolean;
+  onDetected: () => void;
+}
+
+/**
+ * While enabled, re-checks WidgetKit configurations on every foreground
+ * transition (the user may background/foreground several times before
+ * managing to add the widget) and fires onDetected once isTarget matches.
+ */
+export function useWidgetDetection({
+  enabled,
+  isTarget,
+  onDetected,
+}: UseWidgetDetectionOptions) {
+  useEffect(
+    function detectWidgetOnForeground() {
+      if (!enabled) return;
+
+      let cancelled = false;
+
+      async function check() {
+        const widgets = await getInstalledWidgets();
+        if (!cancelled && isTarget(widgets)) {
+          onDetected();
+        }
+      }
+
+      const subscription = AppState.addEventListener("change", (nextState) => {
+        if (nextState === "active") {
+          void check();
+        }
+      });
+
+      return () => {
+        cancelled = true;
+        subscription.remove();
+      };
+    },
+    [enabled, isTarget, onDetected]
+  );
+}

package/src/video.tsx

@@ -0,0 +1,133 @@
+import { useEventListener } from "expo";
+import { useVideoPlayer, VideoView } from "expo-video";
+import { forwardRef, useImperativeHandle, useRef } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+
+/** Playback position mapped over the played range [initialTime, duration] to 0..1, clamped. */
+export function videoProgress(
+  currentTime: number,
+  initialTime: number,
+  duration: number
+): number {
+  if (duration <= 0 || duration <= initialTime) return 0;
+  const progress = (currentTime - initialTime) / (duration - initialTime);
+  return Math.max(0, Math.min(1, progress));
+}
+
+export interface TutorialVideoHandle {
+  startPictureInPicture: () => Promise<void>;
+}
+
+export interface TutorialVideoProps {
+  source: number; // require()d asset
+  /** Start position in seconds (e.g. skip the part covered by a previous step). */
+  initialTime?: number;
+  /** Playback speed multiplier (default 1). */
+  playbackRate?: number;
+  pipEnabled?: boolean;
+  /** Loop playback. Mutually exclusive with onEnded (a looping video never completes). */
+  loop?: boolean;
+  style?: StyleProp<ViewStyle>;
+  /** Reports playback position as 0..1 over the played range. */
+  onProgress?: (progress: number) => void;
+  /** Fires when playback reaches the end (loop off). */
+  onEnded?: () => void;
+}
+
+/**
+ * Muted tutorial player. It never pauses on backgrounding
+ * (staysActiveInBackground) so it has always progressed when the user comes
+ * back. With pipEnabled it detaches into PiP automatically when the app
+ * backgrounds (or programmatically via the handle); while in PiP the video
+ * loops over the full how-to, and playback resumes on screen when PiP ends.
+ */
+export const TutorialVideo = forwardRef<
+  TutorialVideoHandle,
+  TutorialVideoProps
+>(function TutorialVideo(
+  {
+    source,
+    initialTime,
+    playbackRate = 1,
+    pipEnabled = false,
+    loop = false,
+    style,
+    onProgress,
+    onEnded,
+  },
+  ref
+) {
+  const videoViewRef = useRef<VideoView>(null);
+
+  const player = useVideoPlayer(source, (player) => {
+    player.loop = loop;
+    player.muted = true;
+    player.staysActiveInBackground = true;
+    player.playbackRate = playbackRate;
+    player.timeUpdateEventInterval = 0.1;
+    if (initialTime !== undefined) {
+      player.currentTime = initialTime;
+    }
+    player.play();
+  });
+
+  const initialTimeValue = initialTime ?? 0;
+
+  useEventListener(player, "timeUpdate", ({ currentTime }) => {
+    onProgress?.(videoProgress(currentTime, initialTimeValue, player.duration));
+  });
+
+  useEventListener(player, "playToEnd", () => {
+    // expo-video emits playToEnd on every loop iteration (it emits before
+    // seeking back to zero). While looping — i.e. detached into PiP with the
+    // app backgrounded — an end event is not a completion: reporting it
+    // would tear down the UI out from under the user. Only report ends of
+    // the on-screen, loop-off pass.
+    if (player.loop) return;
+    onEnded?.();
+  });
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      startPictureInPicture: async () => {
+        try {
+          await videoViewRef.current?.startPictureInPicture();
+        } catch {
+          // PiP unavailable (device/setting): the flow continues without it.
+        }
+      },
+    }),
+    []
+  );
+
+  return (
+    <VideoView
+      style={style ?? { flex: 1 }}
+      ref={videoViewRef}
+      player={player}
+      nativeControls={false}
+      contentFit="cover"
+      allowsPictureInPicture={pipEnabled}
+      startsPictureInPictureAutomatically={pipEnabled}
+      allowsVideoFrameAnalysis={false}
+      onPictureInPictureStart={() => {
+        // In the floating window the full how-to loops continuously. If the
+        // on-screen playback had already finished (loop is off there), a
+        // stale `loop = true` won't restart an ended player — rewind first.
+        if (
+          player.duration > 0 &&
+          player.currentTime >= player.duration - 0.1
+        ) {
+          player.currentTime = 0;
+        }
+        player.loop = true;
+        player.play();
+      }}
+      onPictureInPictureStop={() => {
+        player.loop = loop;
+        player.play();
+      }}
+    />
+  );
+});