@shopify/react-native-skia 2.9.1 → 2.10.1

package/lib/typescript/lib/module/skia/web/JsiSkImageFactory.d.ts

@@ -5,8 +5,8 @@ export class JsiSkImageFactory extends Host {
     MakeImageFromEncoded(encoded: any): JsiSkImage | null;
     MakeImageFromNativeTextureUnstable(): jest.Mock<any, any, any>;
     MakeImage(info: any, data: any, bytesPerRow: any): JsiSkImage | null;
-    MakeImageFromTexture(_texture: any): jest.Mock<any, any, any>;
-    MakeTextureFromImage(_image: any): jest.Mock<any, any, any>;
+    MakeImageFromNativeTexture(_pointer: any): jest.Mock<any, any, any>;
+    MakeNativeTextureFromImage(_image: any): jest.Mock<any, any, any>;
 }
 import { Host } from "./Host";
 import { JsiSkImage } from "./JsiSkImage";

package/lib/typescript/lib/module/skia/web/JsiSkia.d.ts

@@ -36,8 +36,7 @@ export function JsiSkApi(CanvasKit: any): {
     Video: (url?: any) => Promise<any>;
     Context: (_surface: any, _width: any, _height: any) => jest.Mock<any, any, any>;
     Recorder: () => jest.Mock<any, any, any>;
-    getDevice: () => jest.Mock<any, any, any>;
-    hasDevice: () => boolean;
+    getNativeDevice: () => jest.Mock<any, any, any>;
 };
 import { JsiSkPoint } from "./JsiSkPoint";
 import { JsiSkRRect } from "./JsiSkRRect";

package/lib/typescript/lib/module/views/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./SkiaPictureView";
 export * from "./types";
-export * from "./WebGPUCanvas";
 export * from "./formats";

package/lib/typescript/src/external/reanimated/renderHelpers.d.ts

@@ -1 +1,16 @@
 export declare let HAS_REANIMATED_3: boolean;
+/**
+ * True when the worklets-based Reanimated integration is available
+ * (Reanimated 4 with react-native-worklets providing
+ * registerCustomSerializable). Skia objects use the JSI NativeState pattern
+ * and can only be transferred to worklet runtimes through a custom
+ * serializer, so on native the Reanimated integration requires Reanimated 4 —
+ * Reanimated 3 is not supported.
+ */
+export declare let HAS_REANIMATED_4: boolean;
+/**
+ * Major version of the installed react-native-reanimated package, or null if
+ * it is not installed. Used to give actionable diagnostics when the
+ * integration cannot be enabled.
+ */
+export declare let REANIMATED_VERSION_MAJOR: number | null;

package/lib/typescript/src/skia/SkiaWorkletSerialization.d.ts

@@ -0,0 +1 @@
+export declare const registerSkiaWorkletSerialization: () => void;

package/lib/typescript/src/skia/types/Image/ImageFactory.d.ts

@@ -80,22 +80,31 @@ export interface ImageFactory {
     MakeImage(info: ImageInfo, data: SkData, bytesPerRow: number): SkImage | null;
     /**
      * Creates an SkImage from a WebGPU texture.
-     * This allows using textures rendered by WebGPU in Skia drawings.
+     * This allows using textures rendered by WebGPU in Skia drawings. The
+     * texture crosses the package boundary as a raw pointer: pass
+     * `texture.nativePointer` from a react-native-webgpu GPUTexture created on
+     * the shared device (importDevice(Skia.getNativeDevice())). The native side
+     * takes its own reference, so the handle stays valid even if the JS
+     * GPUTexture is garbage collected — but do not call texture.destroy()
+     * while the image is in use: destroy() releases the underlying GPU
+     * resource regardless of reference counts.
      *
      * Note: This method is only available when the Graphite backend is enabled.
      *
-     * @param texture - A GPUTexture object from the WebGPU API
+     * @param pointer - The WGPUTexture pointer (texture.nativePointer)
      * @returns An SkImage wrapping the texture, or throws if the texture is invalid
      */
-    MakeImageFromTexture(texture: GPUTexture): SkImage;
+    MakeImageFromNativeTexture(pointer: bigint): SkImage;
     /**
      * Creates a WebGPU texture from an SkImage.
-     * This allows using Skia images in WebGPU rendering pipelines.
+     * This allows using Skia images in WebGPU rendering pipelines. The
+     * returned pointer carries one reference and must be adopted exactly once
+     * with react-native-webgpu's adoptTexture(), which owns it from then on.
      *
      * Note: This method is only available when the Graphite backend is enabled.
      *
      * @param image - An SkImage to convert to a texture
-     * @returns A GPUTexture containing the image data, or throws if conversion fails
+     * @returns A WGPUTexture pointer for adoptTexture(), or throws on failure
      */
-    MakeTextureFromImage(image: SkImage): GPUTexture;
+    MakeNativeTextureFromImage(image: SkImage): bigint;
 }

package/lib/typescript/src/skia/types/Skia.d.ts

@@ -86,20 +86,10 @@ export interface Skia {
     NativeBuffer: NativeBufferFactory;
     Recorder(): JsiRecorder;
     /**
-     * Returns whether the Graphite backend is enabled and WebGPU is available.
-     *
-     * @returns true if Graphite/WebGPU is available, false otherwise
+     * Raw WGPUDevice pointer of Skia's Graphite device, as a BigInt. Pass it to
+     * react-native-webgpu's importDevice() to get a GPUDevice sharing Skia's
+     * device (zero-copy interop). Only available on Graphite builds; throws
+     * otherwise.
      */
-    hasDevice(): boolean;
-    /**
-     * Returns the shared WebGPU device used by Skia's Graphite backend.
-     * This allows direct access to the GPU device for WebGPU operations.
-     *
-     * Note: This method is only available when the Graphite backend is enabled.
-     * Use hasDevice() to check availability before calling this method.
-     *
-     * @returns The GPUDevice used by Skia
-     * @throws Error if Graphite backend is not enabled
-     */
-    getDevice(): GPUDevice;
+    getNativeDevice(): bigint;
 }

package/lib/typescript/src/skia/types/index.d.ts

@@ -30,7 +30,6 @@ export * from "./Size";
 export * from "./Paragraph";
 export * from "./Matrix4";
 export * from "./NativeBuffer";
-export * from "./WebGPU";
 export * from "./Recorder";
 export * from "./Video";
 export * from "./Skottie";

package/lib/typescript/src/skia/web/JsiSkImageFactory.d.ts

@@ -11,6 +11,6 @@ export declare class JsiSkImageFactory extends Host implements ImageFactory {
     MakeImageFromEncoded(encoded: SkData): JsiSkImage | null;
     MakeImageFromNativeTextureUnstable(): SkImage;
     MakeImage(info: ImageInfo, data: SkData, bytesPerRow: number): JsiSkImage | null;
-    MakeImageFromTexture(_texture: GPUTexture): SkImage;
-    MakeTextureFromImage(_image: SkImage): GPUTexture;
+    MakeImageFromNativeTexture(_pointer: bigint): SkImage;
+    MakeNativeTextureFromImage(_image: SkImage): bigint;
 }

package/lib/typescript/src/views/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./SkiaPictureView";
 export * from "./types";
-export * from "./WebGPUCanvas";
 export * from "./formats";

package/package.json

@@ -8,7 +8,7 @@
     "setup-skia-web": "scripts/setup-canvaskit.js"
   },
   "title": "React Native Skia",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "High-performance React Native Graphics using Skia",
   "main": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -79,7 +79,8 @@
   "peerDependencies": {
     "react": ">=19.0",
     "react-native": ">=0.78",
-    "react-native-reanimated": ">=3.19.1"
+    "react-native-reanimated": ">=4.0.0",
+    "react-native-worklets": ">=0.7.0"
   },
   "peerDependenciesMeta": {
     "react-native": {
@@ -87,6 +88,9 @@
     },
     "react-native-reanimated": {
       "optional": true
+    },
+    "react-native-worklets": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -127,7 +131,7 @@
     "rimraf": "3.0.2",
     "semantic-release": "^24.1.0",
     "semantic-release-yarn": "^3.0.2",
-    "tar": "^7.5.19",
+    "tar": "^7.5.21",
     "ts-jest": "29.4.3",
     "tsx": "^4.21.0",
     "typescript": "^5.2.2",
@@ -159,8 +163,7 @@
     },
     "ios": {
       "componentProvider": {
-        "SkiaPictureView": "SkiaPictureView",
-        "SkiaWebGPUView": "SkiaWebGPUView"
+        "SkiaPictureView": "SkiaPictureView"
       }
     }
   },

package/react-native-skia.podspec

@@ -75,8 +75,42 @@ framework_names = ['libskia', 'libsvg', 'libskshaper', 'libskparagraph',
                    'libskunicode_core', 'libskunicode_libgrapheme',
                    'libskottie', 'libsksg']
 
-# Add Dawn library for Graphite builds (contains dawn::native symbols)
-framework_names += ['libdawn_combined'] if use_graphite
+# Add Dawn library for Graphite builds (contains dawn::native symbols).
+# libwebgpu_dawn is the same artifact react-native-webgpu vendors. When
+# react-native-webgpu is installed, it provides Dawn for the whole app and
+# vendoring the framework here as well would fail CocoaPods'
+# duplicate-framework-name check, so Skia only vendors it when alone. The
+# skia pod's dawn::native references resolve from webgpu's copy at app link.
+webgpu_pkg_dir = resolve_node_package.call('react-native-webgpu', __dir__)
+has_webgpu_pkg = !webgpu_pkg_dir.nil?
+if use_graphite && has_webgpu_pkg
+  Pod::UI.puts 'react-native-skia: react-native-webgpu detected, Dawn is provided by its libwebgpu_dawn'
+
+  # Both packages must link the exact same Dawn artifact. Compare the release
+  # tag this Graphite build was installed with (libs/.dawn-version) against
+  # the tag react-native-webgpu declares in its package.json `dawn` field.
+  dawn_marker = File.join(__dir__, 'libs', '.dawn-version')
+  if File.exist?(dawn_marker)
+    skia_dawn = File.read(dawn_marker).strip
+    webgpu_pkg = JSON.parse(File.read(File.join(webgpu_pkg_dir, 'package.json')))
+    webgpu_dawn_field = webgpu_pkg['dawn'].to_s
+    if webgpu_dawn_field.empty?
+      raise "react-native-skia: the installed react-native-webgpu " \
+            "(#{webgpu_pkg['version']}) does not declare a `dawn` field in its " \
+            "package.json, so it predates shared-Dawn support and cannot be " \
+            "paired with this Graphite build (which links #{skia_dawn}). " \
+            "Upgrade react-native-webgpu."
+    end
+    webgpu_dawn = "dawn-#{webgpu_dawn_field.tr('/', '-')}"
+    unless skia_dawn == webgpu_dawn
+      raise "react-native-skia: Dawn version mismatch. This Graphite build " \
+            "links #{skia_dawn} but react-native-webgpu links #{webgpu_dawn}. " \
+            "Align the two packages so the app contains exactly one Dawn."
+    end
+    Pod::UI.puts "react-native-skia: Dawn versions match (#{skia_dawn})"
+  end
+end
+framework_names += ['libwebgpu_dawn'] if use_graphite && !has_webgpu_pkg
 
 # Verify that the prebuilt binaries are available (copied in above from the npm
 # packages, or downloaded by install-skia-graphite for in-repo Graphite builds).
@@ -154,9 +188,8 @@ Pod::Spec.new do |s|
     'cpp/rnskia/RNMetalLayerColorSpace.h',
     'cpp/rnskia/RNDawnWindowContext.h',
     'cpp/rnskia/RNDawnWindowContext.cpp',
-    'cpp/rnskia/RNImageProvider.h',
-    'cpp/rnwgpu/**/*.{h,cpp}',
-    'cpp/jsi2/**/*.{h,cpp}'
+    'cpp/rnskia/RNDawnInterop.cpp',
+    'cpp/rnskia/RNImageProvider.h'
   ]
   s.exclude_files = graphite_exclusions unless use_graphite
 

package/src/external/reanimated/renderHelpers.ts

@@ -1,5 +1,22 @@
 export let HAS_REANIMATED_3 = false;
 
+/**
+ * True when the worklets-based Reanimated integration is available
+ * (Reanimated 4 with react-native-worklets providing
+ * registerCustomSerializable). Skia objects use the JSI NativeState pattern
+ * and can only be transferred to worklet runtimes through a custom
+ * serializer, so on native the Reanimated integration requires Reanimated 4 —
+ * Reanimated 3 is not supported.
+ */
+export let HAS_REANIMATED_4 = false;
+
+/**
+ * Major version of the installed react-native-reanimated package, or null if
+ * it is not installed. Used to give actionable diagnostics when the
+ * integration cannot be enabled.
+ */
+export let REANIMATED_VERSION_MAJOR: number | null = null;
+
 try {
   // This logic is convoluted but necessary
   // In most systems, `require("react-native-reanimated")` throws an error, all is well.
@@ -14,6 +31,19 @@ try {
   ) {
     HAS_REANIMATED_3 = true;
   }
+  const majorVersion = parseInt(reanimatedVersion.split(".")[0], 10);
+  if (!isNaN(majorVersion)) {
+    REANIMATED_VERSION_MAJOR = majorVersion;
+  }
+  if (majorVersion >= 4) {
+    try {
+      const worklets = require("react-native-worklets");
+      HAS_REANIMATED_4 =
+        typeof worklets.registerCustomSerializable === "function";
+    } catch (e) {
+      // react-native-worklets not installed
+    }
+  }
 } catch (e) {
   // do nothing
 }

package/src/mock/index.ts

@@ -23,7 +23,6 @@ export const Mock = (CanvasKit: CanvasKit) => {
     ...require("../dom/types"),
     ...require("../dom/nodes"),
     Canvas: require("react-native").View,
-    WebGPUCanvas: require("react-native").View,
     getPreferredHighBitDepthCanvasFormat: () => "rgba16float",
     SkiaPictureView: require("react-native").View,
     JsiSkImage: JsiSkImage,

package/src/skia/NativeSetup.ts

@@ -1,6 +1,8 @@
 import { Platform } from "../Platform";
 import NativeSkiaModule from "../specs/NativeSkiaModule";
 
+import { registerSkiaWorkletSerialization } from "./SkiaWorkletSerialization";
+
 if (Platform.OS !== "web" && global.SkiaApi == null) {
   // Initialize RN Skia
   const SkiaModule = NativeSkiaModule;
@@ -16,4 +18,7 @@ if (Platform.OS !== "web" && global.SkiaApi == null) {
       `Native Skia Module failed to correctly install JSI Bindings! Result: ${result}`
     );
   }
+  // Skia objects use the JSI NativeState pattern and need a custom
+  // serializer to be transferable to worklet runtimes (Reanimated).
+  registerSkiaWorkletSerialization();
 }

package/src/skia/SkiaWorkletSerialization.ts

@@ -0,0 +1,67 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Skia and WebGPU API objects are implemented with the JSI NativeState
+ * pattern: plain JS objects with a shared prototype and native state
+ * attached. Worklets cannot serialize such objects by default (the prototype
+ * would be lost when moving them to another runtime), so we register a
+ * Custom Serializable that:
+ *
+ * - determine: detects native objects via the `__box` method installed on
+ *   every Skia and WebGPU prototype (plain objects never reach the
+ *   custom-serializable path, so this cannot misfire on user data).
+ * - pack: boxes the object into a HostObject wrapper that carries the native
+ *   state and the class brand. HostObjects are transferred by reference.
+ * - unpack: unboxes on the target runtime, re-installing the class prototype
+ *   there and re-attaching the same native state.
+ *
+ * See cpp/jsi/BoxedNativeObject.h for the native side.
+ *
+ * `react-native-worklets` (Reanimated 4) is required for this to work —
+ * without it, Skia and WebGPU objects cannot be captured in worklets or
+ * stored in shared values.
+ */
+
+interface BoxedNativeObject {
+  unbox: () => object;
+  __boxedNativeObject: true;
+}
+
+const determine = (value: object): value is object => {
+  "worklet";
+  return typeof (value as any).__box === "function";
+};
+
+const pack = (value: object): BoxedNativeObject => {
+  "worklet";
+  return (value as any).__box();
+};
+
+const unpack = (packed: BoxedNativeObject): object => {
+  "worklet";
+  return packed.unbox();
+};
+
+export const registerSkiaWorkletSerialization = () => {
+  try {
+    const worklets = require("react-native-worklets");
+    if (typeof worklets.registerCustomSerializable === "function") {
+      worklets.registerCustomSerializable({
+        name: "ReactNativeSkia",
+        determine,
+        pack,
+        unpack,
+      });
+    } else {
+      console.error(
+        "React Native Skia requires react-native-worklets >= 0.7.0 " +
+          "(registerCustomSerializable) to use Skia objects inside worklets. " +
+          "Please upgrade react-native-worklets and react-native-reanimated."
+      );
+    }
+  } catch (e) {
+    // react-native-worklets is not installed. This is fine for apps that do
+    // not use Reanimated: Skia objects simply cannot be used inside worklets
+    // or shared values in this configuration.
+  }
+};

package/src/skia/types/Image/ImageFactory.ts

@@ -97,23 +97,32 @@ export interface ImageFactory {
 
   /**
    * Creates an SkImage from a WebGPU texture.
-   * This allows using textures rendered by WebGPU in Skia drawings.
+   * This allows using textures rendered by WebGPU in Skia drawings. The
+   * texture crosses the package boundary as a raw pointer: pass
+   * `texture.nativePointer` from a react-native-webgpu GPUTexture created on
+   * the shared device (importDevice(Skia.getNativeDevice())). The native side
+   * takes its own reference, so the handle stays valid even if the JS
+   * GPUTexture is garbage collected — but do not call texture.destroy()
+   * while the image is in use: destroy() releases the underlying GPU
+   * resource regardless of reference counts.
    *
    * Note: This method is only available when the Graphite backend is enabled.
    *
-   * @param texture - A GPUTexture object from the WebGPU API
+   * @param pointer - The WGPUTexture pointer (texture.nativePointer)
    * @returns An SkImage wrapping the texture, or throws if the texture is invalid
    */
-  MakeImageFromTexture(texture: GPUTexture): SkImage;
+  MakeImageFromNativeTexture(pointer: bigint): SkImage;
 
   /**
    * Creates a WebGPU texture from an SkImage.
-   * This allows using Skia images in WebGPU rendering pipelines.
+   * This allows using Skia images in WebGPU rendering pipelines. The
+   * returned pointer carries one reference and must be adopted exactly once
+   * with react-native-webgpu's adoptTexture(), which owns it from then on.
    *
    * Note: This method is only available when the Graphite backend is enabled.
    *
    * @param image - An SkImage to convert to a texture
-   * @returns A GPUTexture containing the image data, or throws if conversion fails
+   * @returns A WGPUTexture pointer for adoptTexture(), or throws on failure
    */
-  MakeTextureFromImage(image: SkImage): GPUTexture;
+  MakeNativeTextureFromImage(image: SkImage): bigint;
 }

package/src/skia/types/Skia.ts

@@ -110,20 +110,10 @@ export interface Skia {
   NativeBuffer: NativeBufferFactory;
   Recorder(): JsiRecorder;
   /**
-   * Returns whether the Graphite backend is enabled and WebGPU is available.
-   *
-   * @returns true if Graphite/WebGPU is available, false otherwise
+   * Raw WGPUDevice pointer of Skia's Graphite device, as a BigInt. Pass it to
+   * react-native-webgpu's importDevice() to get a GPUDevice sharing Skia's
+   * device (zero-copy interop). Only available on Graphite builds; throws
+   * otherwise.
    */
-  hasDevice(): boolean;
-  /**
-   * Returns the shared WebGPU device used by Skia's Graphite backend.
-   * This allows direct access to the GPU device for WebGPU operations.
-   *
-   * Note: This method is only available when the Graphite backend is enabled.
-   * Use hasDevice() to check availability before calling this method.
-   *
-   * @returns The GPUDevice used by Skia
-   * @throws Error if Graphite backend is not enabled
-   */
-  getDevice(): GPUDevice;
+  getNativeDevice(): bigint;
 }

package/src/skia/types/index.ts

@@ -30,7 +30,6 @@ export * from "./Size";
 export * from "./Paragraph";
 export * from "./Matrix4";
 export * from "./NativeBuffer";
-export * from "./WebGPU";
 export * from "./Recorder";
 export * from "./Video";
 export * from "./Skottie";

package/src/skia/web/JsiSkImageFactory.ts

@@ -102,11 +102,11 @@ export class JsiSkImageFactory extends Host implements ImageFactory {
     return new JsiSkImage(this.CanvasKit, image);
   }
 
-  MakeImageFromTexture(_texture: GPUTexture): SkImage {
+  MakeImageFromNativeTexture(_pointer: bigint): SkImage {
     return throwNotImplementedOnRNWeb<SkImage>();
   }
 
-  MakeTextureFromImage(_image: SkImage): GPUTexture {
-    return throwNotImplementedOnRNWeb<GPUTexture>();
+  MakeNativeTextureFromImage(_image: SkImage): bigint {
+    return throwNotImplementedOnRNWeb<bigint>();
   }
 }

package/src/skia/web/JsiSkia.ts

@@ -143,10 +143,7 @@ export const JsiSkApi = (CanvasKit: CanvasKit): Skia => ({
   Recorder: () => {
     return throwNotImplementedOnRNWeb<JsiRecorder>();
   },
-  getDevice: () => {
-    return throwNotImplementedOnRNWeb<GPUDevice>();
-  },
-  hasDevice: () => {
-    return false;
+  getNativeDevice: () => {
+    return throwNotImplementedOnRNWeb<bigint>();
   },
 });

package/src/sksg/Container.native.ts

@@ -1,6 +1,10 @@
 import Rea from "../external/reanimated/ReanimatedProxy";
 import type { Skia, SkPicture } from "../skia/types";
-import { HAS_REANIMATED_3 } from "../external/reanimated/renderHelpers";
+import {
+  HAS_REANIMATED_3,
+  HAS_REANIMATED_4,
+  REANIMATED_VERSION_MAJOR,
+} from "../external/reanimated/renderHelpers";
 import type { JsiRecorder } from "../skia/types/Recorder";
 
 import { ReanimatedRecorder } from "./Recorder/ReanimatedRecorder";
@@ -79,10 +83,44 @@ class NativeReanimatedContainer extends Container {
   }
 }
 
+let hasWarnedAboutReanimatedSupport = false;
+
+const reanimatedSupportError = () => {
+  if (REANIMATED_VERSION_MAJOR !== null && REANIMATED_VERSION_MAJOR >= 4) {
+    return (
+      "React Native Skia requires react-native-worklets >= 0.7.0 for its " +
+      "Reanimated integration on native platforms. Reanimated 4 is " +
+      "installed, but react-native-worklets is missing or too old. " +
+      "Please install or upgrade react-native-worklets."
+    );
+  }
+  return (
+    "React Native Skia requires Reanimated 4 (react-native-worklets >= " +
+    "0.7.0) for its Reanimated integration on native platforms. " +
+    "Reanimated 3 is not supported anymore: Skia objects cannot be used " +
+    "inside worklets or shared values with it. " +
+    "Please upgrade to react-native-reanimated >= 4.0.0."
+  );
+};
+
 export const createContainer = (Skia: Skia, nativeId: number) => {
-  if (HAS_REANIMATED_3 && nativeId !== -1) {
+  if (HAS_REANIMATED_4 && nativeId !== -1) {
     return new NativeReanimatedContainer(Skia, nativeId);
   } else {
+    if (HAS_REANIMATED_3 && !HAS_REANIMATED_4) {
+      const message = reanimatedSupportError();
+      if (__DEV__) {
+        // Fail loudly in development — a silent fallback to static rendering
+        // would only be noticed as frozen animations.
+        throw new Error(message);
+      }
+      if (!hasWarnedAboutReanimatedSupport) {
+        hasWarnedAboutReanimatedSupport = true;
+        console.error(
+          `${message} Falling back to static rendering (animations will not run).`
+        );
+      }
+    }
     return new StaticContainer(Skia, nativeId);
   }
 };

package/src/views/index.ts

@@ -1,4 +1,3 @@
 export * from "./SkiaPictureView";
 export * from "./types";
-export * from "./WebGPUCanvas";
 export * from "./formats";