Merge pull request #690 from OskarEichler/codex/viewshot-capture-documentation

docs: correct capture examples and RAW conversion semantics

Author: gre

README.md

@@ -36,29 +36,35 @@ npx pod-install
 ## High Level API
 
 ```js
+import React, {useCallback, useEffect, useRef} from "react";
+import {Image, ScrollView, Text} from "react-native";
 import ViewShot from "react-native-view-shot";
 
-function ExampleCaptureOnMountManually {
+function ExampleCaptureOnMountManually() {
   const ref = useRef();
 
   useEffect(() => {
     // on mount
-    ref.current.capture().then(uri => {
-      console.log("do something with ", uri);
-    });
+    ref.current
+      .capture()
+      .then(uri => {
+        console.log("do something with ", uri);
+      })
+      .catch(console.error);
   }, []);
 
   return (
-    <ViewShot ref={ref} options={{ fileName: "Your-File-Name", format: "jpg", quality: 0.9 }}>
+    <ViewShot
+      ref={ref}
+      options={{fileName: "Your-File-Name", format: "jpg", quality: 0.9}}
+    >
       <Text>...Something to rasterize...</Text>
     </ViewShot>
   );
 }
 
 // alternative
-function ExampleCaptureOnMountSimpler {
-  const ref = useRef();
-
+function ExampleCaptureOnMountSimpler() {
   const onCapture = useCallback(uri => {
     console.log("do something with ", uri);
   }, []);
@@ -72,28 +78,29 @@ function ExampleCaptureOnMountSimpler {
 
 // waiting an image
 
-function ExampleWaitingCapture {
+function ExampleWaitingCapture({imageSource}) {
   const ref = useRef();
 
   const onImageLoad = useCallback(() => {
-    ref.current.capture().then(uri => {
-      console.log("do something with ", uri);
-    })
+    ref.current
+      .capture()
+      .then(uri => {
+        console.log("do something with ", uri);
+      })
+      .catch(console.error);
   }, []);
 
   return (
     <ViewShot ref={ref}>
       <Text>...Something to rasterize...</Text>
-      <Image ... onLoad={onImageLoad} />
+      <Image source={imageSource} onLoad={onImageLoad} />
     </ViewShot>
   );
 }
 
 // capture ScrollView content
 // NB: you may need to go the "imperative way" to use snapshotContentContainer with the scrollview ref instead
-function ExampleCaptureOnMountSimpler {
-  const ref = useRef();
-
+function ExampleCaptureScrollContent() {
   const onCapture = useCallback(uri => {
     console.log("do something with ", uri);
   }, []);
@@ -114,7 +121,7 @@ function ExampleCaptureOnMountSimpler {
 - **`options`**: the same options as in `captureRef` method.
 - **`captureMode`** (string):
   - if not defined (default). the capture is not automatic and you need to use the ref and call `capture()` yourself.
-  - `"mount"`. Capture the view once at mount. (It is important to understand image loading won't be waited, in such case you want to use `"none"` with `viewShotRef.capture()` after `Image#onLoad`.)
+  - `"mount"`. Capture the view once at mount. Image loading is not awaited; omit `captureMode` and call `viewShotRef.current.capture()` after `Image#onLoad` when needed.
   - `"continuous"` EXPERIMENTAL, this will capture A LOT of images continuously. For very specific use-cases.
   - `"update"` EXPERIMENTAL, this will capture images each time React redraw (on did update). For very specific use-cases.
 - **`onCapture`**: when a `captureMode` is defined, this callback will be called with the capture result.
@@ -140,7 +147,7 @@ Returns a Promise of the image URI.
 - **`options`** may include:
   - **`fileName`** _(string)_: (Android only) the file name of the file. Must be at least 3 characters long.
   - **`width`** / **`height`** _(number)_: the width and height of the final image (resized from the View bound. don't provide it if you want the original pixel size).
-  - **`format`** _(string)_: either `png` or `jpg` or `webm` (Android). Defaults to `png`.
+  - **`format`** _(string)_: `png` or `jpg`, plus `webp` and `raw` on Android. Defaults to `png`. `webm` is a deprecated alias for `webp`; it produces WebP image data, not a video.
   - **`quality`** _(number)_: the quality. 0.0 - 1.0 (default). (only available on lossy formats like jpg)
   - **`result`** _(string)_, the method you want to use to save the snapshot, one of:
     - `"tmpfile"` (default): save to a temporary file _(that will only exist for as long as the app is running)_.
@@ -232,11 +239,11 @@ Introduced a new image format RAW. it correspond a ARGB array of pixels.
 
 Advantages:
 
-- no compression, so its supper quick. Screenshot taking is less than 16ms;
+- avoids PNG/JPEG compression; capture time still depends on the view and device.
 
 RAW format supported for `zip-base64`, `base64` and `tmpfile` result types.
 
-RAW file on disk saved in format: `${width}:${height}|${base64}` string.
+RAW files contain an ASCII `${width}:${height}|` header followed by binary pixel bytes. The `base64` result instead returns that header followed by base64-encoded pixels; `zip-base64` returns the header followed by base64-encoded, zlib-compressed pixels.
 
 ### zip-base64
 
@@ -246,45 +253,60 @@ approach for capturing screen views and deliver them to the react side.
 
 ### How to work with zip-base64 and RAW format?
 
+Capture in React Native, then send the result and format to a Node.js process for conversion. Node's `fs` and `zlib` modules are not built into React Native.
+
 ```js
-const fs = require("fs");
-const zlib = require("zlib");
-const PNG = require("pngjs").PNG;
-const Buffer = require("buffer").Buffer;
+import {Platform} from "react-native";
+import {captureRef} from "react-native-view-shot";
 
 const format = Platform.OS === "android" ? "raw" : "png";
 const result = Platform.OS === "android" ? "zip-base64" : "base64";
 
-captureRef(this.ref, {result, format}).then(data => {
-  // expected pattern 'width:height|', example: '1080:1731|'
-  const resolution = /^(\d+):(\d+)\|/g.exec(data);
-  const width = (resolution || ["", 0, 0])[1];
-  const height = (resolution || ["", 0, 0])[2];
-  const base64 = data.substr((resolution || [""])[0].length || 0);
-
-  // convert from base64 to Buffer
-  const buffer = Buffer.from(base64, "base64");
-  // un-compress data
-  const inflated = zlib.inflateSync(buffer);
-  // compose PNG
-  const png = new PNG({width, height});
-  png.data = inflated;
-  const pngData = PNG.sync.write(png);
-  // save composed PNG
-  fs.writeFileSync(output, pngData);
-});
+captureRef(viewRef, {result, format})
+  .then(data => {
+    // Send {data, format} to your Node.js conversion process.
+  })
+  .catch(console.error);
+```
+
+In Node.js:
+
+```js
+const fs = require("node:fs");
+const zlib = require("node:zlib");
+const {PNG} = require("pngjs");
+
+function saveCapture(data, format, outputPath) {
+  let pngData;
+  if (format === "raw") {
+    const resolution = /^(\d+):(\d+)\|/.exec(data);
+    if (!resolution) throw new Error("Missing RAW dimensions");
+    const width = Number(resolution[1]);
+    const height = Number(resolution[2]);
+    const compressed = Buffer.from(data.slice(resolution[0].length), "base64");
+    const pixels = zlib.inflateSync(compressed);
+    if (!width || !height || pixels.length !== width * height * 4) {
+      throw new Error("Invalid RAW dimensions or pixel data");
+    }
+    const png = new PNG({width, height});
+    png.data = pixels;
+    pngData = PNG.sync.write(png);
+  } else {
+    // The iOS/Windows fallback is already PNG, not zlib-compressed RAW.
+    pngData = Buffer.from(data, "base64");
+  }
+  fs.writeFileSync(outputPath, pngData);
+}
 ```
 
 Keep in mind that packaging PNG data is a CPU consuming operation as a `zlib.inflate`.
 
 Hint: use `process.fork()` approach for converting raw data into PNGs.
 
-> Note: code is tested in large commercial project.
-
-> Note #2: Don't forget to add packages into your project:
+> Install the PNG encoder in your Node.js conversion project (`zlib` is built in):
 >
 > ```bash
-> npm install pngjs zlib
+> npm install pngjs
 > ```
 
 ## Troubleshooting / FAQ
@@ -328,20 +350,23 @@ This is because the snapshot image result is in real pixel size where the width/
 A prop may be necessary to properly capture GL Surface View in the view tree:
 
 ```js
-/**
-  * if true and when view is a SurfaceView or have it in the view tree, view will be captured.
-  * False by default, because it can have signoficant performance impact
-  */
-handleGLSurfaceViewOnAndroid?: boolean;
+// Opt in to SurfaceView capture; it can have a significant performance cost.
+captureRef(viewRef, {handleGLSurfaceViewOnAndroid: true});
 ```
 
 ### Trying to share the capture result with `expo-sharing`?
 
-`tmpfile` or the default capture result works best for this. Just be sure to prepend `file://` to result before you call `shareAsync`.
+`tmpfile` or the default capture result works best for this. Add `file://` only when it is absent; Android already returns a file URI.
 
 ```js
 captureRef(viewRef)
-  .then((uri) => Sharing.shareAsync(`file://${uri}`, options)
+  .then(uri =>
+    Sharing.shareAsync(
+      uri.startsWith("file://") ? uri : `file://${uri}`,
+      options,
+    ),
+  )
+  .catch(console.error);
 ```
 
 ---

example-web/README.md

@@ -96,19 +96,17 @@ See `.github/workflows/ci.yml` - the `test-web-example` job runs all Playwright
 
 **CI Artifacts:**
 
-- `web-snapshots-reference`: Current reference snapshots (download to update local snapshots)
-- `web-snapshots-diff`: Visual diffs when tests fail (actual vs expected)
+- `web-snapshots-actual`: Actual, expected and diff images from failed comparisons
 - `playwright-report`: Full HTML test report
 - `playwright-test-results`: Detailed test results
 
 **When snapshots differ:**
 
 - The CI will show a clear message in the GitHub Actions summary
-- Download the `web-snapshots-reference` artifact
-- Replace `example-web/e2e/snapshots/reference/` with the downloaded files
-- Commit the updated snapshots
+- Run `./scripts/update-snapshots-from-ci.sh <RUN_ID>` from `example-web/` to import only the actual images from `web-snapshots-actual`
+- Review every changed reference image and commit only intended visual changes
 
-**Note:** Snapshots are platform-specific (Linux vs macOS). The CI runs on Linux, so you may need to update snapshots when running locally on macOS.
+**Note:** Committed reference images are generated on Linux. Local non-Linux runs use separate platform-suffixed images; do not replace the Linux references with macOS or Windows output. See [snapshot guidance](e2e/snapshots/README.md).
 
 ## Related