react-native-frame-capture 1.0.1 → 1.1.0

package/package.json

@@ -1,196 +1,199 @@
-{
-  "name": "react-native-frame-capture",
-  "version": "1.0.1",
-  "description": "Reliable screen capture for React Native Android. Capture frames at intervals with customizable overlays and storage options.",
-  "main": "./lib/module/index.js",
-  "types": "./lib/typescript/src/index.d.ts",
-  "exports": {
-    ".": {
-      "source": "./src/index.tsx",
-      "types": "./lib/typescript/src/index.d.ts",
-      "default": "./lib/module/index.js"
-    },
-    "./app.plugin.js": "./app.plugin.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src",
-    "lib",
-    "android",
-    "ios",
-    "cpp",
-    "plugin/build",
-    "*.podspec",
-    "react-native.config.js",
-    "app.plugin.js",
-    "!ios/build",
-    "!android/build",
-    "!android/gradle",
-    "!android/gradlew",
-    "!android/gradlew.bat",
-    "!android/local.properties",
-    "!**/__tests__",
-    "!**/__fixtures__",
-    "!**/__mocks__",
-    "!**/.*"
-  ],
-  "scripts": {
-    "example": "yarn workspace react-native-frame-capture-example",
-    "test": "jest --passWithNoTests",
-    "typecheck": "tsc",
-    "lint": "eslint \"**/*.{js,ts,tsx}\"",
-    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
-    "prepare": "bob build",
-    "release": "release-it --only-version",
-    "run-dev": "cd example/android && gradlew clean && cd ../../ && yarn prepare && yarn example android"
-  },
-  "keywords": [
-    "react-native",
-    "android",
-    "screen-capture",
-    "frame-capture",
-    "screenshot",
-    "screen-recording",
-    "interval-capture",
-    "media-projection",
-    "turbo-module",
-    "expo",
-    "capture",
-    "frame",
-    "screen",
-    "recording",
-    "fps",
-    "foreground-service",
-    "overlay",
-    "watermark",
-    "image-overlay",
-    "text-overlay",
-    "kotlin",
-    "typescript",
-    "background-capture",
-    "periodic-capture"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nasyx-rakeeb/react-native-frame-capture.git"
-  },
-  "author": "Nasyx Rakeeb <nasyxrakeeb2@gmail.com> (https://github.com/nasyx-rakeeb)",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/nasyx-rakeeb/react-native-frame-capture/issues"
-  },
-  "homepage": "https://github.com/nasyx-rakeeb/react-native-frame-capture#readme",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "devDependencies": {
-    "@commitlint/config-conventional": "^19.8.1",
-    "@eslint/compat": "^1.3.2",
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.35.0",
-    "@evilmartians/lefthook": "^1.12.3",
-    "@expo/config-plugins": "^9.0.0",
-    "@react-native-community/cli": "20.0.1",
-    "@react-native/babel-preset": "0.81.1",
-    "@react-native/eslint-config": "^0.81.1",
-    "@release-it/conventional-changelog": "^10.0.1",
-    "@types/jest": "^29.5.14",
-    "@types/react": "^19.1.0",
-    "commitlint": "^19.8.1",
-    "del-cli": "^6.0.0",
-    "eslint": "^9.35.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
-    "jest": "^29.7.0",
-    "prettier": "^3.6.2",
-    "react": "19.1.0",
-    "react-native": "0.81.1",
-    "react-native-builder-bob": "^0.40.13",
-    "release-it": "^19.0.4",
-    "turbo": "^2.5.6",
-    "typescript": "^5.9.2"
-  },
-  "peerDependencies": {
-    "expo": "*",
-    "react": "*",
-    "react-native": "*"
-  },
-  "peerDependenciesMeta": {
-    "expo": {
-      "optional": true
-    }
-  },
-  "workspaces": [
-    "example"
-  ],
-  "packageManager": "yarn@3.6.1",
-  "jest": {
-    "preset": "react-native",
-    "modulePathIgnorePatterns": [
-      "<rootDir>/example/node_modules",
-      "<rootDir>/lib/"
-    ]
-  },
-  "commitlint": {
-    "extends": [
-      "@commitlint/config-conventional"
-    ]
-  },
-  "release-it": {
-    "git": {
-      "commitMessage": "chore: release ${version}",
-      "tagName": "v${version}"
-    },
-    "npm": {
-      "publish": true
-    },
-    "github": {
-      "release": true
-    },
-    "plugins": {
-      "@release-it/conventional-changelog": {
-        "preset": {
-          "name": "angular"
-        }
-      }
-    }
-  },
-  "prettier": {
-    "quoteProps": "consistent",
-    "singleQuote": true,
-    "tabWidth": 2,
-    "trailingComma": "es5",
-    "useTabs": false
-  },
-  "react-native-builder-bob": {
-    "source": "src",
-    "output": "lib",
-    "targets": [
-      [
-        "module",
-        {
-          "esm": true
-        }
-      ],
-      [
-        "typescript",
-        {
-          "project": "tsconfig.build.json"
-        }
-      ]
-    ]
-  },
-  "codegenConfig": {
-    "name": "FrameCaptureSpec",
-    "type": "modules",
-    "jsSrcsDir": "src",
-    "android": {
-      "javaPackageName": "com.framecapture"
-    }
-  },
-  "create-react-native-library": {
-    "languages": "kotlin-objc",
-    "type": "turbo-module",
-    "version": "0.54.8"
-  }
-}
+{
+  "name": "react-native-frame-capture",
+  "version": "1.1.0",
+  "description": "Reliable screen capture for React Native Android. Capture frames at intervals with customizable overlays and storage options.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "plugin/build",
+    "*.podspec",
+    "react-native.config.js",
+    "app.plugin.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-frame-capture-example",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "release": "release-it --only-version",
+    "run-dev": "cd example/android && gradlew clean && cd ../../ && yarn prepare && yarn example android"
+  },
+  "keywords": [
+    "react-native",
+    "android",
+    "screen-capture",
+    "frame-capture",
+    "screenshot",
+    "screen-recording",
+    "interval-capture",
+    "media-projection",
+    "turbo-module",
+    "view-shot",
+    "react-native-view-shot",
+    "expo",
+    "capture",
+    "frame",
+    "screen",
+    "recording",
+    "fps",
+    "foreground-service",
+    "overlay",
+    "watermark",
+    "image-overlay",
+    "text-overlay",
+    "kotlin",
+    "javascript",
+    "typescript",
+    "background-capture",
+    "periodic-capture"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nasyx-rakeeb/react-native-frame-capture.git"
+  },
+  "author": "Nasyx Rakeeb <nasyxrakeeb2@gmail.com> (https://github.com/nasyx-rakeeb)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nasyx-rakeeb/react-native-frame-capture/issues"
+  },
+  "homepage": "https://github.com/nasyx-rakeeb/react-native-frame-capture#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/compat": "^1.3.2",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.35.0",
+    "@evilmartians/lefthook": "^1.12.3",
+    "@expo/config-plugins": "^9.0.0",
+    "@react-native-community/cli": "20.0.1",
+    "@react-native/babel-preset": "0.81.1",
+    "@react-native/eslint-config": "^0.81.1",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.0",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29.7.0",
+    "prettier": "^3.6.2",
+    "react": "19.1.0",
+    "react-native": "0.81.1",
+    "react-native-builder-bob": "^0.40.13",
+    "release-it": "^19.0.4",
+    "turbo": "^2.5.6",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@3.6.1",
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "FrameCaptureSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.framecapture"
+    }
+  },
+  "create-react-native-library": {
+    "languages": "kotlin-objc",
+    "type": "turbo-module",
+    "version": "0.54.8"
+  }
+}

package/src/NativeFrameCapture.ts

@@ -56,6 +56,13 @@ export type OverlayErrorEvent = {
   message: string;
 };
 
+export type ChangeDetectedEvent = {
+  changePercent: number;
+  threshold: number;
+  captured: boolean;
+  timeSinceLastCapture: number;
+};
+
 /**
  * TurboModule specification for FrameCapture
  * Defines the native methods implemented in Kotlin
@@ -70,6 +77,7 @@ export interface Spec extends TurboModule {
   readonly onCapturePause: EventEmitter<CapturePauseEvent>;
   readonly onCaptureResume: EventEmitter<CaptureResumeEvent>;
   readonly onOverlayError: EventEmitter<OverlayErrorEvent>;
+  readonly onChangeDetected: EventEmitter<ChangeDetectedEvent>;
 
   // Methods
   requestPermission(): Promise<string>;

package/src/constants.ts

@@ -67,3 +67,48 @@ export const MAX_QUALITY = 100;
  * @deprecated Use advanced.storage.warningThreshold in CaptureOptions instead
  */
 export const STORAGE_WARNING_THRESHOLD = 100 * 1024 * 1024; // 100MB
+
+// =============================================================================
+// Change Detection Mode Constants
+// =============================================================================
+
+/**
+ * Default change detection threshold (percentage of pixels changed)
+ */
+export const DEFAULT_CHANGE_THRESHOLD = 5;
+
+/**
+ * Minimum change detection threshold
+ */
+export const MIN_CHANGE_THRESHOLD = 0;
+
+/**
+ * Maximum change detection threshold
+ */
+export const MAX_CHANGE_THRESHOLD = 100;
+
+/**
+ * Default minimum interval between captures in change detection mode (ms)
+ */
+export const DEFAULT_CHANGE_MIN_INTERVAL = 500;
+
+/**
+ * Default maximum interval between captures in change detection mode (ms)
+ * 0 means disabled - no forced captures when screen is static
+ */
+export const DEFAULT_CHANGE_MAX_INTERVAL = 0;
+
+/**
+ * Default sample rate for change detection (every Nth pixel)
+ */
+export const DEFAULT_CHANGE_SAMPLE_RATE = 16;
+
+/**
+ * Minimum sample rate (1 = every pixel)
+ */
+export const MIN_CHANGE_SAMPLE_RATE = 1;
+
+/**
+ * Maximum sample rate
+ */
+export const MAX_CHANGE_SAMPLE_RATE = 64;

package/src/normalize.ts

@@ -4,13 +4,22 @@
  * @module normalize
  */
 
-import type { CaptureOptions } from './types';
+import type { CaptureOptions, CaptureMode } from './types';
 
 /**
  * Flat options structure expected by native code
  */
 export interface NativeCaptureOptions {
-  interval: number;
+  // Capture mode
+  captureMode: CaptureMode;
+  interval?: number;
+  // Change detection options (flat)
+  changeThreshold?: number;
+  changeMinInterval?: number;
+  changeMaxInterval?: number;
+  changeSampleRate?: number;
+  changeDetectionRegion?: any;
+  // Image options
   quality: number;
   format: 'png' | 'jpeg';
   saveFrames?: boolean;
@@ -48,10 +57,21 @@ export function normalizeOptions(
   const { capture, image, storage, performance, notification, overlays } =
     options;
 
+  const captureMode = capture.mode || 'interval';
+  const changeDetection = capture.changeDetection;
+
   return {
-    // Capture config
+    // Capture mode
+    captureMode,
     interval: capture.interval,
 
+    // Change detection config (flattened)
+    changeThreshold: changeDetection?.threshold,
+    changeMinInterval: changeDetection?.minInterval,
+    changeMaxInterval: changeDetection?.maxInterval,
+    changeSampleRate: changeDetection?.sampleRate,
+    changeDetectionRegion: changeDetection?.detectionRegion,
+
     // Image config
     quality: image.quality,
     format: image.format,

package/src/types.ts

@@ -50,6 +50,7 @@ export enum CaptureEventType {
   CAPTURE_PAUSE = 'onCapturePause',
   CAPTURE_RESUME = 'onCaptureResume',
   OVERLAY_ERROR = 'onOverlayError',
+  CHANGE_DETECTED = 'onChangeDetected',
 }
 
 // ============================================================================
@@ -71,6 +72,11 @@ export type PositionPreset =
   | 'bottom-right'
   | 'center';
 
+/**
+ * Capture mode type
+ */
+export type CaptureMode = 'interval' | 'change-detection';
+
 // ============================================================================
 // Capture Configuration
 // ============================================================================
@@ -124,12 +130,32 @@ export interface NotificationOptions {
   showResumeAction?: boolean;
 }
 
+/**
+ * Change detection configuration
+ */
+export interface ChangeDetectionConfig {
+  /** Minimum percentage of pixels that must change to trigger capture (0-100) */
+  threshold: number;
+  /** Minimum milliseconds between captures even with rapid changes (default: 500) */
+  minInterval?: number;
+  /** Maximum milliseconds between captures regardless of changes (0 = disabled, default: 0) */
+  maxInterval?: number;
+  /** Pixel sampling rate for performance (1 = every pixel, 16 = every 16th pixel, default: 16) */
+  sampleRate?: number;
+  /** Region of interest for change detection (default: full screen) */
+  detectionRegion?: CaptureRegion;
+}
+
 /**
  * Capture behavior configuration
  */
 export interface CaptureConfig {
-  /** Milliseconds between captures (100-60000) */
-  interval: number;
+  /** Capture mode: 'interval' or 'change-detection' (default: 'interval') */
+  mode?: CaptureMode;
+  /** Milliseconds between captures (100-60000) - required when mode is 'interval' */
+  interval?: number;
+  /** Change detection settings - required when mode is 'change-detection' */
+  changeDetection?: ChangeDetectionConfig;
 }
 
 /**
@@ -300,6 +326,7 @@ import type {
   CapturePauseEvent,
   CaptureResumeEvent,
   OverlayErrorEvent,
+  ChangeDetectedEvent,
 } from './NativeFrameCapture';
 
 export type {
@@ -311,6 +338,7 @@ export type {
   CapturePauseEvent,
   CaptureResumeEvent,
   OverlayErrorEvent,
+  ChangeDetectedEvent,
 };
 
 /**