@symbiote-native/screen-capture 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,151 @@
 {
   "name": "@symbiote-native/screen-capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "expo-screen-capture wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Blocks or detects screenshots/screen recordings and offers an app-switcher privacy blur.",
+  "license": "MIT",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-screen-capture",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "screen-capture",
+    "screenshot",
+    "privacy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/screen-capture"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/screen-capture#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./svelte": {
+      "types": "./build/svelte/index.d.ts",
+      "default": "./build/svelte/index.js"
+    },
+    "./solid": {
+      "types": "./build/solid/index.d.ts",
+      "default": "./build/solid/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-screen-capture": "57.0.3",
+    "expo-modules-core": "57.0.20"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/engine": "^1.4.0",
+    "@symbiote-native/react": "^3.1.0",
+    "@symbiote-native/solid": "^3.0.5",
+    "@symbiote-native/angular": "^3.1.3",
+    "@symbiote-native/svelte": "^3.0.5",
+    "@symbiote-native/vue": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/engine": "1.4.0",
+    "@symbiote-native/angular": "3.1.3",
+    "@symbiote-native/react": "3.1.0",
+    "@symbiote-native/solid": "3.0.5",
+    "@symbiote-native/vue": "3.1.0",
+    "@symbiote-native/test-utils": "0.4.5",
+    "@symbiote-native/svelte": "3.0.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
 }

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+export * from '../core';
+export { PreventScreenCaptureService } from './services/prevent-screen-capture.service';
+export { ScreenshotListenerService } from './services/screenshot-listener.service';
+export { PermissionsService } from './services/permissions.service';

package/src/angular/services/permissions.service/index.ts

@@ -0,0 +1,11 @@
+import { Injectable } from '@angular/core';
+import { PermissionsServiceBase } from '@symbiote-native/angular';
+import { getPermissionsAsync, requestPermissionsAsync } from '../../../core';
+import type { PermissionResponse } from '../../../core';
+
+@Injectable({ providedIn: 'root' })
+export class PermissionsService extends PermissionsServiceBase<PermissionResponse> {
+  constructor() {
+    super(getPermissionsAsync, requestPermissionsAsync);
+  }
+}

package/src/angular/services/prevent-screen-capture.service/index.ts

@@ -0,0 +1,25 @@
+// Angular twin of `../../react`'s `usePreventScreenCapture`, `connect()` shape matching
+// `@symbiote-native/keep-awake`'s own `KeepAwakeService`
+
+import { effect, inject, Injectable, Injector } from '@angular/core';
+import {
+  allowScreenCaptureAsync,
+  preventScreenCaptureAsync,
+} from '../../../core';
+
+@Injectable({ providedIn: 'root' })
+export class PreventScreenCaptureService {
+  private readonly injector = inject(Injector);
+
+  connect(key: string = 'default'): void {
+    effect(
+      onCleanup => {
+        preventScreenCaptureAsync(key);
+        onCleanup(() => {
+          allowScreenCaptureAsync(key);
+        });
+      },
+      { injector: this.injector },
+    );
+  }
+}

package/src/angular/services/screenshot-listener.service/index.ts

@@ -0,0 +1,22 @@
+// Angular twin of `../../react`'s `useScreenshotListener`, `connect()` shape matching
+// `@symbiote-native/keep-awake`'s own `KeepAwakeService`
+
+import { effect, inject, Injectable, Injector } from '@angular/core';
+import { addScreenshotListener } from '../../../core';
+
+@Injectable({ providedIn: 'root' })
+export class ScreenshotListenerService {
+  private readonly injector = inject(Injector);
+
+  connect(listener: () => void): void {
+    effect(
+      onCleanup => {
+        const subscription = addScreenshotListener(listener);
+        onCleanup(() => {
+          subscription.remove();
+        });
+      },
+      { injector: this.injector },
+    );
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,17 @@
+export {
+  addScreenshotListener,
+  allowScreenCaptureAsync,
+  disableAppSwitcherProtectionAsync,
+  enableAppSwitcherProtectionAsync,
+  getPermissionsAsync,
+  isAvailableAsync,
+  preventScreenCaptureAsync,
+  removeScreenshotListener,
+  requestPermissionsAsync,
+} from './screen-capture';
+export {
+  PermissionStatus,
+  type EventSubscription,
+  type PermissionExpiration,
+  type PermissionResponse,
+} from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,27 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription, PermissionResponse } from 'expo-modules-core';
+
+const EXPO_SCREEN_CAPTURE_MODULE_NAME = 'ExpoScreenCapture';
+
+export const ON_SCREENSHOT_EVENT_NAME = 'onScreenshot';
+
+// App-switcher blur is iOS-only (absent from ScreenCaptureModule.kt); permissions are
+// Android-only in practice - each optional method is checked at its own call site.
+export type INativeScreenCaptureModule = {
+  addListener(
+    eventName: typeof ON_SCREENSHOT_EVENT_NAME,
+    listener: () => void,
+  ): EventSubscription;
+  removeAllListeners(eventName: typeof ON_SCREENSHOT_EVENT_NAME): void;
+  preventScreenCapture?(): Promise<void>;
+  allowScreenCapture?(): Promise<void>;
+  enableAppSwitcherProtection?(blurIntensity: number): Promise<void>;
+  disableAppSwitcherProtection?(): Promise<void>;
+  getPermissionsAsync?(): Promise<PermissionResponse>;
+  requestPermissionsAsync?(): Promise<PermissionResponse>;
+};
+
+export const expoScreenCapture =
+  requireNativeModule<INativeScreenCaptureModule>(
+    EXPO_SCREEN_CAPTURE_MODULE_NAME,
+  );

package/src/core/permissions-runtime.ts

@@ -0,0 +1,26 @@
+// The get/request wrapper every adapter's `usePermissions` needs, extracted once so
+// `src/vue`/`src/solid`/`src/svelte`/`src/react` each supply only their own state primitive
+
+export type IPermissionsApi<TPermission> = {
+  get: () => Promise<TPermission>;
+  request: () => Promise<TPermission>;
+};
+
+export function createPermissionsApi<TPermission>(
+  getMethod: () => Promise<TPermission>,
+  requestMethod: () => Promise<TPermission>,
+  record: (response: TPermission) => void,
+): IPermissionsApi<TPermission> {
+  return {
+    get: async () => {
+      const response = await getMethod();
+      record(response);
+      return response;
+    },
+    request: async () => {
+      const response = await requestMethod();
+      record(response);
+      return response;
+    },
+  };
+}

package/src/core/screen-capture.ts

@@ -0,0 +1,102 @@
+import { PermissionStatus, UnavailabilityError } from 'expo-modules-core';
+import type { EventSubscription, PermissionResponse } from 'expo-modules-core';
+import { expoScreenCapture, ON_SCREENSHOT_EVENT_NAME } from './native-module';
+
+const NATIVE_MODULE_NAME = 'ScreenCapture';
+const activeKeys = new Set<string>();
+
+export async function isAvailableAsync(): Promise<boolean> {
+  return (
+    !!expoScreenCapture.preventScreenCapture &&
+    !!expoScreenCapture.allowScreenCapture
+  );
+}
+
+/** Repeated calls with the same `key` are no-ops until a matching `allowScreenCaptureAsync`. */
+export async function preventScreenCaptureAsync(
+  key: string = 'default',
+): Promise<void> {
+  if (!expoScreenCapture.preventScreenCapture) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'preventScreenCaptureAsync',
+    );
+  }
+  if (!activeKeys.has(key)) {
+    activeKeys.add(key);
+    await expoScreenCapture.preventScreenCapture();
+  }
+}
+
+export async function allowScreenCaptureAsync(
+  key: string = 'default',
+): Promise<void> {
+  if (!expoScreenCapture.allowScreenCapture) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'allowScreenCaptureAsync',
+    );
+  }
+  activeKeys.delete(key);
+  if (activeKeys.size === 0) {
+    await expoScreenCapture.allowScreenCapture();
+  }
+}
+
+/** iOS only; throws `UnavailabilityError` on Android. */
+export async function enableAppSwitcherProtectionAsync(
+  blurIntensity: number = 0.5,
+): Promise<void> {
+  if (!expoScreenCapture.enableAppSwitcherProtection) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'enableAppSwitcherProtectionAsync',
+    );
+  }
+  await expoScreenCapture.enableAppSwitcherProtection(blurIntensity);
+}
+
+/** iOS only; throws `UnavailabilityError` on Android. */
+export async function disableAppSwitcherProtectionAsync(): Promise<void> {
+  if (!expoScreenCapture.disableAppSwitcherProtection) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'disableAppSwitcherProtectionAsync',
+    );
+  }
+  await expoScreenCapture.disableAppSwitcherProtection();
+}
+
+export function addScreenshotListener(listener: () => void): EventSubscription {
+  return expoScreenCapture.addListener(ON_SCREENSHOT_EVENT_NAME, listener);
+}
+
+/** @deprecated use `subscription.remove()` instead. */
+export function removeScreenshotListener(
+  subscription: EventSubscription,
+): void {
+  subscription.remove();
+}
+
+const defaultPermissionsResponse: PermissionResponse = {
+  granted: true,
+  expires: 'never',
+  canAskAgain: true,
+  status: PermissionStatus.GRANTED,
+};
+
+/** Only Android requires a permission to detect screenshots; iOS always resolves granted. */
+export async function getPermissionsAsync(): Promise<PermissionResponse> {
+  if (expoScreenCapture.getPermissionsAsync) {
+    return expoScreenCapture.getPermissionsAsync();
+  }
+  return defaultPermissionsResponse;
+}
+
+/** Only Android requires a permission to detect screenshots; iOS always resolves granted. */
+export async function requestPermissionsAsync(): Promise<PermissionResponse> {
+  if (expoScreenCapture.requestPermissionsAsync) {
+    return expoScreenCapture.requestPermissionsAsync();
+  }
+  return defaultPermissionsResponse;
+}

package/src/react/hooks/use-permissions/index.ts

@@ -0,0 +1,49 @@
+// Same shape as `@symbiote-native/brightness`'s own `usePermissions` by design - each package
+// owns its copy. The mount fetch has nobody to reject to, so its failure lands in the 4th
+// tuple slot (`error`)
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getPermissionsAsync, requestPermissionsAsync } from '../../../core';
+import type { PermissionResponse } from '../../../core';
+
+export function usePermissions(): [
+  PermissionResponse | null,
+  () => Promise<PermissionResponse>,
+  () => Promise<PermissionResponse>,
+  Error | null,
+] {
+  const isMounted = useRef(true);
+  const [status, setStatus] = useState<PermissionResponse | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const getPermission = useCallback(async () => {
+    const response = await getPermissionsAsync();
+    if (isMounted.current) {
+      setStatus(response);
+      setError(null);
+    }
+    return response;
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    const response = await requestPermissionsAsync();
+    if (isMounted.current) {
+      setStatus(response);
+      setError(null);
+    }
+    return response;
+  }, []);
+
+  useEffect(() => {
+    isMounted.current = true;
+    getPermission().catch((cause: unknown) => {
+      if (isMounted.current)
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+    });
+    return () => {
+      isMounted.current = false;
+    };
+  }, [getPermission]);
+
+  return [status, requestPermission, getPermission, error];
+}

package/src/react/hooks/use-prevent-screen-capture/index.ts

@@ -0,0 +1,17 @@
+// React lifecycle wiring over the framework-agnostic core (core/screen-capture.ts): prevents on
+// mount, allows on unmount, mirroring upstream's `usePreventScreenCapture`
+
+import { useEffect } from 'react';
+import {
+  allowScreenCaptureAsync,
+  preventScreenCaptureAsync,
+} from '../../../core';
+
+export function usePreventScreenCapture(key: string = 'default'): void {
+  useEffect(() => {
+    preventScreenCaptureAsync(key);
+    return () => {
+      allowScreenCaptureAsync(key);
+    };
+  }, [key]);
+}

package/src/react/hooks/use-screenshot-listener/index.ts

@@ -0,0 +1,14 @@
+// React lifecycle wiring over the framework-agnostic core (core/screen-capture.ts): subscribes
+// on mount, unsubscribes on unmount, mirroring upstream's `useScreenshotListener`
+
+import { useEffect } from 'react';
+import { addScreenshotListener } from '../../../core';
+
+export function useScreenshotListener(listener: () => void): void {
+  useEffect(() => {
+    const subscription = addScreenshotListener(listener);
+    return () => {
+      subscription.remove();
+    };
+  }, [listener]);
+}

package/src/react/index.ts

@@ -0,0 +1,4 @@
+export * from '../core';
+export { usePreventScreenCapture } from './hooks/use-prevent-screen-capture';
+export { useScreenshotListener } from './hooks/use-screenshot-listener';
+export { usePermissions } from './hooks/use-permissions';

package/src/solid/index.ts

@@ -0,0 +1,4 @@
+export * from '../core';
+export { createPreventScreenCapture } from './primitives/create-prevent-screen-capture';
+export { createScreenshotListener } from './primitives/create-screenshot-listener';
+export { createPermissions } from './primitives/create-permissions';

package/src/solid/primitives/create-permissions.ts

@@ -0,0 +1,39 @@
+// Solid lifecycle wiring over core/screen-capture.ts. The synchronous fetch has nobody to reject
+// to, so its failure lands in `error` instead of escaping as an unhandled rejection
+
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+import { getPermissionsAsync, requestPermissionsAsync } from '../../core';
+import type { PermissionResponse } from '../../core';
+import { createPermissionsApi } from '../../core/permissions-runtime';
+
+export function createPermissions(): {
+  status: Accessor<PermissionResponse | null>;
+  error: Accessor<Error | null>;
+  request: () => Promise<PermissionResponse>;
+  get: () => Promise<PermissionResponse>;
+} {
+  const [status, setStatus] = createSignal<PermissionResponse | null>(null);
+  const [error, setError] = createSignal<Error | null>(null);
+  let isDisposed = false;
+
+  const api = createPermissionsApi(
+    getPermissionsAsync,
+    requestPermissionsAsync,
+    response => {
+      if (isDisposed) return;
+      setStatus(response);
+      setError(null);
+    },
+  );
+
+  api.get().catch((cause: unknown) => {
+    if (isDisposed) return;
+    setError(cause instanceof Error ? cause : new Error(String(cause)));
+  });
+
+  onCleanup(() => {
+    isDisposed = true;
+  });
+
+  return { status, error, request: api.request, get: api.get };
+}

package/src/solid/primitives/create-prevent-screen-capture.ts

@@ -0,0 +1,14 @@
+// Solid twin of `../../react`'s `usePreventScreenCapture`: prevents synchronously in the
+// primitive body, allows on `onCleanup` - same "nothing can interleave" reasoning as
+// `create-keep-awake.ts` (`@symbiote-native/keep-awake`)
+
+import { onCleanup } from 'solid-js';
+import { allowScreenCaptureAsync, preventScreenCaptureAsync } from '../../core';
+
+export function createPreventScreenCapture(key: string = 'default'): void {
+  preventScreenCaptureAsync(key);
+
+  onCleanup(() => {
+    allowScreenCaptureAsync(key);
+  });
+}

package/src/solid/primitives/create-screenshot-listener.ts

@@ -0,0 +1,13 @@
+// Solid twin of `../../react`'s `useScreenshotListener`: subscribes synchronously in the
+// primitive body, unsubscribes on `onCleanup`
+
+import { onCleanup } from 'solid-js';
+import { addScreenshotListener } from '../../core';
+
+export function createScreenshotListener(listener: () => void): void {
+  const subscription = addScreenshotListener(listener);
+
+  onCleanup(() => {
+    subscription.remove();
+  });
+}

package/src/svelte/index.ts

@@ -0,0 +1,4 @@
+export * from '../core';
+export { usePreventScreenCapture } from './use-prevent-screen-capture.svelte';
+export { useScreenshotListener } from './use-screenshot-listener.svelte';
+export { usePermissions } from './use-permissions.svelte';

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls svelte's ambient globals ($state/$effect/...) into this package's tsc program,
+// same fix as `packages/navigation/src/svelte/svelte-ambient.d.ts`
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,7 @@
+// Re-exports the existing harness instead of a third copy (packages/sqlite and
+// packages/navigation already carry one, not part of either package's public exports)
+export {
+  createSvelteHarness,
+  loadComponent,
+  type ISvelteHarness,
+} from '../../../sqlite/src/svelte/svelte-compile.test-helper';

package/src/svelte/use-permissions.svelte.ts

@@ -0,0 +1,41 @@
+// Boxed-getter shape matches `@symbiote-native/brightness`'s own rune by design - each package
+// owns its copy rather than depend on a sibling install-optional package
+
+import { getPermissionsAsync, requestPermissionsAsync } from '../core';
+import type { PermissionResponse } from '../core';
+import { createPermissionsApi } from '../core/permissions-runtime';
+
+export function usePermissions(): {
+  readonly status: PermissionResponse | null;
+  readonly error: Error | null;
+  request: () => Promise<PermissionResponse>;
+  get: () => Promise<PermissionResponse>;
+} {
+  let status = $state<PermissionResponse | null>(null);
+  let error = $state<Error | null>(null);
+  const api = createPermissionsApi(
+    getPermissionsAsync,
+    requestPermissionsAsync,
+    response => {
+      status = response;
+      error = null;
+    },
+  );
+
+  $effect(() => {
+    api.get().catch((cause: unknown) => {
+      error = cause instanceof Error ? cause : new Error(String(cause));
+    });
+  });
+
+  return {
+    get status(): PermissionResponse | null {
+      return status;
+    },
+    get error(): Error | null {
+      return error;
+    },
+    request: api.request,
+    get: api.get,
+  };
+}

package/src/svelte/use-prevent-screen-capture.svelte.ts

@@ -0,0 +1,12 @@
+// Svelte twin of `../react`'s `usePreventScreenCapture`: prevents on mount, allows on unmount
+
+import { allowScreenCaptureAsync, preventScreenCaptureAsync } from '../core';
+
+export function usePreventScreenCapture(key: string = 'default'): void {
+  $effect(() => {
+    preventScreenCaptureAsync(key);
+    return () => {
+      allowScreenCaptureAsync(key);
+    };
+  });
+}

package/src/svelte/use-screenshot-listener.svelte.ts

@@ -0,0 +1,13 @@
+// Svelte twin of `../react`'s `useScreenshotListener`: subscribes on mount, unsubscribes on
+// unmount
+
+import { addScreenshotListener } from '../core';
+
+export function useScreenshotListener(listener: () => void): void {
+  $effect(() => {
+    const subscription = addScreenshotListener(listener);
+    return () => {
+      subscription.remove();
+    };
+  });
+}