skia-canvas 2.0.2 → 3.0.1

package/README.md

@@ -16,21 +16,24 @@
   <a href="https://github.com/samizdatco/skia-canvas/discussions">Discussion Forum</a>
 </div>
 
----
+<div align="center">
+
+### [Version 3.0 now available](https://github.com/samizdatco/skia-canvas/discussions/255)
+
+</div>
 
-Skia Canvas is a browser-less implementation of the HTML Canvas drawing API for Node.js. It is based on Google’s [Skia](https://skia.org) graphics engine and, accordingly, produces very similar results to Chrome’s `<canvas>` element. The library is well suited for use on desktop machines where you can render hardware-accelerated graphics to a window and on the server where it can output a variety of image formats.
+---
 
-While the primary goal of this project is to provide a reliable emulation of the [standard API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) according to the [spec](https://html.spec.whatwg.org/multipage/canvas.html), it also extends it in a number of areas to take greater advantage of Skia's advanced graphical features and provide a more expressive coding environment.
+Skia Canvas is a Node.js implementation of the HTML Canvas drawing [API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) for both on- and off-screen rendering. Since it uses Google’s [Skia](https://skia.org) graphics engine, its output is very similar to Chrome’s [`<canvas>`](https://html.spec.whatwg.org/multipage/canvas.html) element — though it's also capable of things the browser’s Canvas still can't achieve.
 
 In particular, Skia Canvas:
 
-  - is fast and compact since rendering takes place on the GPU and all the heavy lifting is done by native code written in Rust and C++
-  - can render to [windows][window] using an OS-native graphics pipeline and provides a browser-like [UI event][win_bind] framework
-  - generates images in both raster (JPEG, PNG, & WEBP) and vector (PDF & SVG) formats
-  - can save images to [files][saveAs], return them as [Buffers][toBuffer], or encode [dataURL][toDataURL_ext] strings
+  - generates images in vector (PDF & SVG) as well as bitmap (JPEG, PNG, & WEBP) formats
+  - can draw to interactive GUI [windows][window] and provides a browser-like [event][win_bind] framework
+  - can save images to [files][toFile], encode to [dataURL][toURL] strings, and return [Buffers][toBuffer] or [Sharp][sharp] objects
   - uses native threads in a [user-configurable][multithreading] worker pool for asynchronous rendering and file I/O
-  - can create [multiple ‘pages’][newPage] on a given canvas and then [output][saveAs] them as a single, multi-page PDF or an image-sequence saved to multiple files
-  - can [simplify][p2d_simplify], [blunt][p2d_round], [combine][bool-ops], [excerpt][p2d_trim], and [atomize][p2d_points] bézier paths using [efficient](https://www.youtube.com/watch?v=OmfliNQsk88) boolean operations or point-by-point [interpolation][p2d_interpolate]
+  - can create [multiple ‘pages’][newPage] on a given canvas and then [output][toFile] them as a single, multi-page PDF or an image-sequence saved to multiple files
+  - can [simplify][p2d_simplify], [blunt][p2d_round], [combine][bool-ops], [excerpt][p2d_trim], and [atomize][p2d_points] Bézier paths using [efficient](https://www.youtube.com/watch?v=OmfliNQsk88) boolean operations or point-by-point [interpolation][p2d_interpolate]
   - provides [3D perspective][createProjection()] transformations in addition to [scaling][scale()], [rotation][rotate()], and [translation][translate()]
   - can fill shapes with vector-based [Textures][createTexture()] in addition to bitmap-based [Patterns][createPattern()] and supports line-drawing with custom [markers][lineDashMarker]
   - supports the full set of [CSS filter][filter] image processing operators
@@ -41,6 +44,7 @@ In particular, Skia Canvas:
     - proportional [letter-spacing][letterSpacing], [word-spacing][wordSpacing], and [leading][c2d_font]
     - support for [variable fonts][VariableFonts] and transparent mapping of weight values
     - use of non-system fonts [loaded][fontlibrary-use] from local files
+  - can be used for server-side image rendering on standard Linux hosts and ‘serverless’ platforms like Vercel and AWS Lambda
 
 ## Installation
 
@@ -51,68 +55,161 @@ npm install skia-canvas
 
 This will download a pre-compiled library from the project’s most recent [release](https://github.com/samizdatco/skia-canvas/releases).
 
-## Platform Support
 
-The underlying Rust library uses [N-API][node_napi] v8 which allows it to run on Node.js versions:
-  - v12.22+
-  - v14.17+
-  - v15.12+
-  - v16.0.0 and later
+### `pnpm`
+If you use the `pnpm` package manager, it will not download `skia-canvas`'s platform-native binary unless you explicitly allow it. You can do this interactively via the ‘approve builds’ command (note that you need to press `<space>` to toggle the selection and then `<enter>` to proceed):
 
-Pre-compiled binaries are available for:
+```bash
+pnpm install skia-canvas
+pnpm approve-builds
+```
+In non-interactive scenarios (like building via CI), you can approve the build step when you add `skia-canvas` to your project:
 
-  - Linux (x64 & arm64)
-  - macOS (x64 & Apple silicon)
-  - Windows (x64)
+```bash
+pnpm install skia-canvas --allow-build=skia-canvas
+```
 
-Nearly everything you need is statically linked into the library. A notable exception is the [Fontconfig](https://www.freedesktop.org/wiki/Software/fontconfig/) library which must be installed separately if you’re running on Linux.
+Alternatively, you can add a [`pnpm.onlyBuiltDependencies`](https://pnpm.io/9.x/package_json#pnpmonlybuiltdependencies) entry to your `package.json` file to mark the build-step as allowed:
+```json
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["skia-canvas"]
+  }
+}
+```
 
-## Running in Docker
 
-The library is compatible with Linux systems using [glibc](https://www.gnu.org/software/libc/) 2.28 or later as well as Alpine Linux (x64 & arm64) and the [musl](https://musl.libc.org) C library it favors. In both cases, Fontconfig must be installed on the system for `skia-canvas` to operate correctly.
 
-If you are setting up a [Dockerfile](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) that uses [`node`](https://hub.docker.com/_/node) as its basis, the simplest approach is to set your `FROM` image to one of the (Debian-derived) defaults like `node:lts`, `node:18`, `node:16`, `node:14-buster`, `node:12-buster`, `node:bullseye`, `node:buster`, or simply:
-```dockerfile
-FROM node
-```
+## Platform Support
+
+Skia Canvas runs on Linux, macOS, or Windows as well as serverless platforms like Vercel and AWS Lambda. Precompiled versions of the library’s native code will be automatically downloaded in the appropriate architecture (`arm64` or `x64`) when you install it via npm.
+
+The underlying Rust library uses [N-API][node_napi] v8 which allows it to run on all [currently supported](https://nodejs.org/en/about/previous-releases) Node.js releases, and it is backward compatible with versions going back to v12.22+, v14.17+, v15.12+, and v16+.
+
+### Linux
 
-You can also use the ‘slim’ image if you manually install fontconfig:
+The library is compatible with Linux systems using [glibc](https://www.gnu.org/software/libc/) 2.28 or later as well as Alpine Linux and the [musl](https://musl.libc.org) C library it favors. It will make use of the system’s `fontconfig` settings in `/etc/fonts` if they exist but will otherwise fall back to using a [placeholder configuration](https://github.com/samizdatco/skia-canvas/blob/main/lib/fonts/fonts.conf), looking for installed fonts at commonly used Linux paths.
 
+### Docker
+
+If you are setting up a [Dockerfile](https://nodejs.org/en/docs/guides/nodejs-docker-webapp/) that uses [`node`](https://hub.docker.com/_/node) as its basis, the simplest approach is to set your `FROM` image to one of the (Debian-derived) defaults like `node:lts`, `node:22`, `node:24-bookworm`, or simply:
 ```dockerfile
-FROM node:slim
-RUN apt-get update && apt-get install -y -q --no-install-recommends libfontconfig1
+FROM node
 ```
 
 If you wish to use Alpine as the underlying distribution, you can start with something along the lines of:
 
 ```dockerfile
 FROM node:alpine
-RUN apk update && apk add fontconfig
 ```
 
+### AWS Lambda
+
+Skia Canvas depends on libraries that aren't present in the standard Lambda [runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). You can add these to your function by uploading a ‘[layer](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html)’ (a zip file containing the required libraries and `node_modules` directory) and configuring your function to use it.
+
+
+<details><summary>
+
+**Detailed AWS instructions**
+
+</summary>
+
+#### Adding the Skia Canvas layer to your AWS account
+
+1. Look in the **Assets** section of Skia Canvas’s [current release](https://github.com/samizdatco/skia-canvas/releases/latest) and download the `aws-lambda-x64.zip` or `aws-lambda-arm64.zip` file (depending on your architecture) but don’t decompress it
+2. Go to the AWS Lambda [Layers console](https://console.aws.amazon.com/lambda/home/#/layers) and click the **Create Layer** button, then fill in the fields:
+  - **Name**: `skia-canvas` (or whatever you want)
+  - **Description**: you might want to note the Skia Canvas version here
+  - **Compatible architectures**: select **x86_64** or **arm64** depending on which zip you chose
+  - **Compatible runtimes**: select **Node.js 22.x** (and/or 20.x)
+3. Click the **Choose file** button and select the zip file you downloaded in Step 1, then click **Create**
+
+Alternatively, you can use the [`aws` command line tool](https://github.com/aws/aws-cli) to create the layer. This bash script will fetch the skia-canvas version of your choice and make it available to your Lambda functions.
+```sh
+#!/usr/bin/env bash
+VERSION=3.0 # the skia-canvas version to include
+PLATFORM=arm64 # arm64 or x64
+
+curl -sLO https://github.com/samizdatco/skia-canvas/releases/download/v${VERSION}/aws-lambda-${PLATFORM}.zip
+aws lambda publish-layer-version \
+    --layer-name "skia-canvas" \
+    --description "Skia Canvas ${VERSION} layer" \
+    --zip-file "fileb://aws-lambda-${PLATFORM}.zip" \
+    --compatible-runtimes "nodejs20.x" "nodejs22.x" \
+    --compatible-architectures "${X/#x/x86_}"
+```
+
+#### Using the layer in a Lambda function
+
+You can now use this layer in any function you create in the [Functions console](https://console.aws.amazon.com/lambda/home/#/functions). After creating a new function, click the **Add a Layer** button and you can select your newly created Skia Canvas layer from the **Custom Layers** layer source.
+
+Note that the layer only includes Skia Canvas and its dependencies—any other npm modules you want to use will need to be bundled into your function. To prevent the `skia-canvas` module from being doubly-included, make sure you add it to the  `devDependencies` section (**not** the regular `dependencies` section) of your package.json file.
+
+</details>
+
+
+### Next.js / Webpack
+
+If you are using a framework like Next.js that bundles your server-side code with Webpack, you'll need to mark `skia-canvas` as an ‘external’, otherwise its platform-native binary file will be excluded from the final build. Try adding these options to your `next.config.ts` file:
+
+```js
+const nextConfig: NextConfig = {
+  serverExternalPackages: ['skia-canvas'],
+  webpack: (config, options) => {
+    if (options.isServer){
+      config.externals = [
+        ...config.externals,
+        {'skia-canvas': 'commonjs skia-canvas'},
+      ]
+    }
+    return config
+  }
+};
+```
+
+
 ## Compiling from Source
 
 If prebuilt binaries aren’t available for your system you’ll need to compile the portions of this library that directly interface with Skia.
 
 Start by installing:
 
-  1. The [Rust compiler](https://www.rust-lang.org/tools/install) and cargo package manager using [`rustup`](https://rust-lang.github.io/rustup/)
-  2. A C compiler toolchain (either LLVM/Clang or MSVC)
+  1. A recent version of `git` (older versions have difficulties with Skia's submodules)
+  2. The [Rust compiler](https://www.rust-lang.org/tools/install) and cargo package manager using [`rustup`](https://rust-lang.github.io/rustup/)
+  3. A C compiler toolchain (either LLVM/Clang or MSVC)
   4. Python 3 (used by Skia's [build process](https://skia.org/docs/user/build/))
-  3. The [Ninja](https://ninja-build.org) build system
-  5. On Linux: Fontconfig and OpenSSL
+  5. The [Ninja](https://ninja-build.org) build system
+  6. On Linux: Fontconfig and OpenSSL
 
-[Detailed instructions](https://github.com/rust-skia/rust-skia#building) for setting up these dependencies on different operating systems can be found in the ‘Building’ section of the Rust Skia documentation. Once all the necessary compilers and libraries are present, running `npm run build` will give you a usable library (after a fairly lengthy compilation process).
+[Detailed instructions](https://github.com/rust-skia/rust-skia#building) for setting up these dependencies on different operating systems can be found in the ‘Building’ section of the Rust Skia documentation. The Dockerfiles in the [containers](https://github.com/samizdatco/skia-canvas/tree/main/containers) directory may also be useful for identifying needed dependencies. Once all the necessary compilers and libraries are present, running `npm run build` will give you a usable library (after a fairly lengthy compilation process).
 
-## Multithreading
+## Global Settings
 
-When rendering canvases in the background (e.g., by using the asynchronous [saveAs][saveAs] or [toBuffer][toBuffer] methods), tasks are spawned in a thread pool managed by the [rayon][rayon] library. By default it will create up to as many threads as your CPU has cores. You can see this default value by inspecting any [Canvas][canvas] object's [`engine.threads`][engine] property. If you wish to override this default, you can set the `SKIA_CANVAS_THREADS` environment variable to your preferred value.
+> There are a handful of settings that can only be configured at launch and will apply to all the canvases you create in your script. The sections below describe the different [environment variables][node_env] you can set to make global changes. You can either set them as part of your command line invocation, or place them in a `.env` file in your project directory and use Node 20's [`--env-file` argument][node_env_arg] to load them all at once.
+
+### Multithreading
+
+When rendering canvases in the background (e.g., by using the asynchronous [toFile][toFile] or [toBuffer][toBuffer] methods), tasks are spawned in a thread pool managed by the [rayon][rayon] library. By default it will create up to as many threads as your CPU has cores. You can see this default value by inspecting any [Canvas][canvas] object's [`engine.threads`][engine] property. If you wish to override this default, you can set the `SKIA_CANVAS_THREADS` environment variable to your preferred value.
 
 For example, you can limit your asynchronous processing to two simultaneous tasks by running your script with:
 ```bash
 SKIA_CANVAS_THREADS=2 node my-canvas-script.js
 ```
 
+### Argument Validation
+
+There are a number of situations where the browser API will react to invalid arguments by silently ignoring the method call rather than throwing an error. For example, these lines will simply have no effect:
+
+```js
+ctx.fillRect(0, 0, 100, "october")
+ctx.lineTo(NaN, 0)
+```
+
+
+Skia Canvas does its best to emulate these quirks, but allows you to opt into a stricter mode in which it will throw TypeErrors in these situations (which can be useful for debugging).
+
+Set the `SKIA_CANVAS_STRICT` environment variable to `1` or `true` to enable this mode.
+
 ## Example Usage
 
 ### Generating image files
@@ -197,6 +294,87 @@ win.on("draw", e => {
   ctx.fill()
 })
 ```
+
+### Integrating with [Sharp.js][sharp]
+
+```js
+import sharp from 'sharp'
+import {Canvas, loadImage} from 'skia-canvas'
+
+let canvas = new Canvas(400, 400),
+    ctx = canvas.getContext("2d"),
+    {width, height} = canvas,
+    [x, y] = [width/2, height/2]
+
+ctx.fillStyle = 'red'
+ctx.fillRect(0, 0, x, y)
+ctx.fillStyle = 'orange'
+ctx.fillRect(x, y, x, y)
+
+// Render the canvas to a Sharp object on a background thread then desaturate
+await canvas.toSharp().modulate({saturation:.25}).jpeg().toFile("faded.jpg")
+
+// Convert an ImageData to a Sharp object and save a grayscale version
+let imgData = ctx.getImageData(0, 0, width, height, {matte:'white', density:2})
+await imgData.toSharp().grayscale().png().toFile("black-and-white.png")
+
+// Create an image using Sharp then draw it to the canvas as an Image object
+let sharpImage = sharp({create:{ width:x, height:y, channels:4, background:"skyblue" }})
+let canvasImage = await loadImage(sharpImage)
+ctx.drawImage(canvasImage, x, 0)
+await canvas.saveAs('mosaic.png')
+```
+
+## Benchmarks
+In these benchmarks, Skia Canvas is tested running in two modes: serial and async. When running serially, each rendering operation is awaited before continuing to the next test iteration. When running asynchronously, all the test iterations are begun at once and are executed in parallel using the library’s multi-threading support.
+
+[See full results here…](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/index.md)
+
+### [Startup latency](https://github.com/samizdatco/canvas-benchmarks/tree/main/tests/cold-start.js)
+| Library              | Per Run   | Total Time (100 iterations)                   |
+| -------------------- | --------- | --------------------------------------------- |
+| *canvaskit-wasm*     | `  25 ms` | ` 2.46 s` ![ ](./docs/assets/benchmarks.svg#cold-start_wasm)      |
+| *canvas*             | `  88 ms` | ` 8.76 s` ![ ](./docs/assets/benchmarks.svg#cold-start_canvas)    |
+| *@napi-rs/canvas*    | `  73 ms` | ` 7.30 s` ![ ](./docs/assets/benchmarks.svg#cold-start_napi)      |
+| *skia-canvas*        | `  <1 ms` | `  33 ms` ![ ](./docs/assets/benchmarks.svg#cold-start_skia-sync) |
+
+### [Bezier curves](https://github.com/samizdatco/canvas-benchmarks/tree/main/tests/beziers.js)
+| Library                                                       | Per Run   | Total Time (20 iterations)                  |
+| ------------------------------------------------------------- | --------- | ------------------------------------------- |
+| *canvaskit-wasm* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/beziers_wasm.png)            | ` 789 ms` | `15.77 s` ![ ](./docs/assets/benchmarks.svg#beziers_wasm)       |
+| *canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/beziers_canvas.png)                  | ` 488 ms` | ` 9.76 s` ![ ](./docs/assets/benchmarks.svg#beziers_canvas)     |
+| *@napi-rs/canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/beziers_napi.png)           | ` 233 ms` | ` 4.65 s` ![ ](./docs/assets/benchmarks.svg#beziers_napi)       |
+| *skia-canvas (serial)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/beziers_skia-sync.png) | ` 137 ms` | ` 2.74 s` ![ ](./docs/assets/benchmarks.svg#beziers_skia-sync)  |
+| *skia-canvas (async)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/beziers_skia-async.png) | `  28 ms` | ` 558 ms` ![ ](./docs/assets/benchmarks.svg#beziers_skia-async) |
+
+### [SVG to PNG](https://github.com/samizdatco/canvas-benchmarks/tree/main/tests/from-svg.js)
+| Library                                                        | Per Run   | Total Time (100 iterations)                  |
+| -------------------------------------------------------------- | --------- | -------------------------------------------- |
+| canvaskit-wasm                                                 | ` ————— ` | ` ————— `   *not supported*                  |
+| *canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/from-svg_canvas.png)                  | ` 122 ms` | `12.20 s` ![ ](./docs/assets/benchmarks.svg#from-svg_canvas)     |
+| *@napi-rs/canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/from-svg_napi.png)           | `  98 ms` | ` 9.76 s` ![ ](./docs/assets/benchmarks.svg#from-svg_napi)       |
+| *skia-canvas (serial)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/from-svg_skia-sync.png) | `  59 ms` | ` 5.91 s` ![ ](./docs/assets/benchmarks.svg#from-svg_skia-sync)  |
+| *skia-canvas (async)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/from-svg_skia-async.png) | `  11 ms` | ` 1.06 s` ![ ](./docs/assets/benchmarks.svg#from-svg_skia-async) |
+
+### [Scale/rotate images](https://github.com/samizdatco/canvas-benchmarks/tree/main/tests/image-blit.js)
+| Library                                                          | Per Run   | Total Time (50 iterations)                     |
+| ---------------------------------------------------------------- | --------- | ---------------------------------------------- |
+| *canvaskit-wasm* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/image-blit_wasm.png)            | ` 279 ms` | `13.95 s` ![ ](./docs/assets/benchmarks.svg#image-blit_wasm)       |
+| *canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/image-blit_canvas.png)                  | ` 284 ms` | `14.21 s` ![ ](./docs/assets/benchmarks.svg#image-blit_canvas)     |
+| *@napi-rs/canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/image-blit_napi.png)           | ` 116 ms` | ` 5.78 s` ![ ](./docs/assets/benchmarks.svg#image-blit_napi)       |
+| *skia-canvas (serial)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/image-blit_skia-sync.png) | ` 100 ms` | ` 5.01 s` ![ ](./docs/assets/benchmarks.svg#image-blit_skia-sync)  |
+| *skia-canvas (async)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/image-blit_skia-async.png) | `  19 ms` | ` 937 ms` ![ ](./docs/assets/benchmarks.svg#image-blit_skia-async) |
+
+### [Basic text](https://github.com/samizdatco/canvas-benchmarks/tree/main/tests/text.js)
+| Library                                                    | Per Run   | Total Time (200 iterations)              |
+| ---------------------------------------------------------- | --------- | ---------------------------------------- |
+| *canvaskit-wasm* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/text_wasm.png)            | `  24 ms` | ` 4.74 s` ![ ](./docs/assets/benchmarks.svg#text_wasm)       |
+| *canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/text_canvas.png)                  | `  24 ms` | ` 4.86 s` ![ ](./docs/assets/benchmarks.svg#text_canvas)     |
+| *@napi-rs/canvas* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/text_napi.png)           | `  19 ms` | ` 3.82 s` ![ ](./docs/assets/benchmarks.svg#text_napi)       |
+| *skia-canvas (serial)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/text_skia-sync.png) | `  21 ms` | ` 4.24 s` ![ ](./docs/assets/benchmarks.svg#text_skia-sync)  |
+| *skia-canvas (async)* [👁️](https://github.com/samizdatco/canvas-benchmarks/blob/main/results/darwin-arm64/2025-08-15/snapshots/text_skia-async.png) | `   4 ms` | ` 781 ms` ![ ](./docs/assets/benchmarks.svg#text_skia-async) |
+
+
 ## Acknowledgements
 
 This project is deeply indebted to the work of the [Rust Skia project](https://github.com/rust-skia/rust-skia) whose Skia bindings provide a safe and idiomatic interface to the mess of C++ that lies underneath. Many thanks to the developers of [node-canvas](https://github.com/Automattic/node-canvas) for their terrific set of unit tests. In the absence of an [Acid Test](https://www.acidtests.org) for canvas, these routines were invaluable.
@@ -204,7 +382,7 @@ This project is deeply indebted to the work of the [Rust Skia project](https://g
 
 ### Notable contributors
 
-- [@mpaparno](https://github.com/mpaparno) contributed support for SVG rendering, raw image-buffer handling, WEBP import/export and numerous bugfixes
+- [@mpaparno](https://github.com/mpaparno) contributed support for SVG rendering, raw image-buffer handling, WEBP import/export and numerous bug fixes
 - [@Salmondx](https://github.com/Salmondx) developed the initial Raw image loading & rendering routines
 - [@lucasmerlin](https://github.com/lucasmerlin) helped get GPU rendering working on Vulkan
 - [@cprecioso](https://github.com/cprecioso) & [@saantonandre](https://github.com/saantonandre) corrected and expanded upon the TypeScript type definitions
@@ -229,15 +407,18 @@ This project is deeply indebted to the work of the [Rust Skia project](https://g
 [p2d_round]: https://skia-canvas.org/api/path2d#round
 [p2d_simplify]: https://skia-canvas.org/api/path2d#simplify
 [p2d_trim]: https://skia-canvas.org/api/path2d#trim
-[saveAs]: https://skia-canvas.org/api/canvas#saveas
+[toFile]: https://skia-canvas.org/api/canvas#tofile
 [textwrap]: https://skia-canvas.org/api/context#textwrap
 [toBuffer]: https://skia-canvas.org/api/canvas#tobuffer
-[toDataURL_ext]: https://skia-canvas.org/api/canvas#todataurl
+[toURL]: https://skia-canvas.org/api/canvas#tourl
 [win_bind]: https://skia-canvas.org/api/window#on--off--once
 [window]: https://skia-canvas.org/api/window
 [multithreading]: https://skia-canvas.org/getting-started#multithreading
 [node_napi]: https://nodejs.org/api/n-api.html#node-api-version-matrix
+[node_env]: https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs
+[node_env_arg]: https://nodejs.org/dist/latest-v22.x/docs/api/cli.html#--env-fileconfig
 [rayon]: https://crates.io/crates/rayon
+[sharp]: https://sharp.pixelplumbing.com
 [VariableFonts]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide
 [filter]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/filter
 [letterSpacing]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/letterSpacing

package/lib/browser.js

@@ -2,6 +2,9 @@
 // Browser equivalents of the skia-canvas convenience initializers and polyfills for
 // the Canvas object’s newPage & export methods
 //
+// OPTIONAL DEPENDENCY: be sure to include JSZip in your project bundle if you want to
+// make use of multi-page toFile() downloads
+//
 
 "use strict"
 
@@ -21,8 +24,6 @@ class Canvas{
     let elt = document.createElement('canvas'),
         pages = []
 
-    Object.defineProperty(elt, "async", {value:true, writable:false, enumerable:true})
-
     for (var [prop, get] of Object.entries({
       png: () => asBuffer(elt, 'image/png'),
       jpg: () => asBuffer(elt, 'image/jpeg'),
@@ -42,7 +43,11 @@ class Canvas{
         return Object.assign(elt, {width, height}).getContext("2d")
       },
 
-      saveAs(filename, args){
+      saveAs(){
+        throw Error("Canvas.saveAs() has been renamed to Canvas.toFile")
+      },
+
+      toFile(filename, args){
         args = typeof args=='number' ? {quality:args} : args
         let opts = exportOptions(this.pages, {filename, ...args}),
             {pattern, padding, mime, quality, matte, density, archive} = opts,
@@ -59,163 +64,18 @@ class Canvas{
         return asBuffer(canvas, mime, quality, matte)
       },
 
-      [_toURL_]: elt.toDataURL.bind(elt),
-      toDataURL(extension="png", args={}){
+      toURL(extension="png", args={}){
         args = typeof args=='number' ? {quality:args} : args
         let opts = exportOptions(this.pages, {extension, ...args}),
             {mime, quality, matte, pages, density} = opts,
             canvas = atScale(pages, density, matte)[0],
-            url = canvas[canvas===elt ? _toURL_ : 'toDataURL'](mime, quality);
+            url = canvas.toDataURL(mime, quality);
         return Promise.resolve(url)
       }
     })
   }
 }
 
-
-
-//
-// Zip (pace Phil Katz & q.v. https://github.com/jimmywarting/StreamSaver.js)
-//
-
-class Crc32 {
-  static for(data){
-    return new Crc32().append(data).get()
-  }
-
-  constructor(){ this.crc = -1 }
-
-  get(){ return ~this.crc }
-
-  append(data){
-    var crc = this.crc | 0,
-        table = this.table
-    for (var offset = 0, len = data.length | 0; offset < len; offset++) {
-      crc = (crc >>> 8) ^ table[(crc ^ data[offset]) & 0xFF]
-    }
-    this.crc = crc
-    return this
-  }
-
-}
-
-Crc32.prototype.table = (() => {
-  var i, j, t, table = []
-  for (i = 0; i < 256; i++) {
-    t = i
-    for (j = 0; j < 8; j++) {
-      t = (t & 1)
-        ? (t >>> 1) ^ 0xEDB88320
-        : t >>> 1
-    }
-    table[i] = t
-  }
-  return table
-})()
-
-function calloc(size){
-  let array = new Uint8Array(size),
-      view = new DataView(array.buffer),
-      buf = {
-        array, view, size,
-        set8(at, to){ view.setUint8(at, to); return buf },
-        set16(at, to){ view.setUint16(at, to, true); return buf },
-        set32(at, to){ view.setUint32(at, to, true); return buf },
-        bytes(at, to){ array.set(to, at); return buf },
-      }
-  return buf
-}
-
-class Zip{
-  static encoder = new TextEncoder()
-
-  constructor(directory){
-    let now = new Date()
-    Object.assign(this, {
-      directory,
-      offset: 0,
-      files: [],
-      time: (((now.getHours() << 6) | now.getMinutes()) << 5) | now.getSeconds() / 2,
-      date: ((((now.getFullYear() - 1980) << 4) | (now.getMonth() + 1)) << 5) | now.getDate(),
-    })
-    this.add(directory)
-  }
-
-  async add(filename, blob){
-    let folder = !blob,
-        name = Zip.encoder.encode(`${this.directory}/${folder ? '' : filename}`),
-        data = new Uint8Array(folder ? 0 : await blob.arrayBuffer()),
-        preamble = 30 + name.length,
-        descriptor = preamble + data.length,
-        postamble = 16,
-        {offset} = this
-
-    let header = calloc(26)
-      .set32(0, 0x08080014)       // zip version
-      .set16(6, this.time)        // time
-      .set16(8, this.date)        // date
-      .set32(10, Crc32.for(data)) // checksum
-      .set32(14, data.length)     // compressed size (w/ zero compression)
-      .set32(18, data.length)     // un-compressed size
-      .set16(22, name.length)     // filename length (utf8 bytes)
-    offset += preamble
-
-    let payload = calloc(preamble + data.length + postamble)
-      .set32(0, 0x04034b50)   // local header signature
-      .bytes(4, header.array) // ...header fields...
-      .bytes(30, name)        // filename
-      .bytes(preamble, data)  // blob bytes
-    offset += data.length
-
-    payload
-      .set32(descriptor, 0x08074b50)                    // signature
-      .bytes(descriptor + 4, header.array.slice(10,22)) // length & filemame
-    offset += postamble
-
-    this.files.push({offset, folder, name, header, payload})
-    this.offset = offset
-  }
-
-  toBuffer(){
-    // central directory record
-    let length = this.files.reduce((len, {name}) => 46 + name.length + len, 0),
-        cdr = calloc(length + 22),
-        index = 0
-
-    for (var {offset, name, header, folder} of this.files){
-      cdr.set32(index, 0x02014b50)            // archive file signature
-         .set16(index + 4, 0x0014)            // version
-         .bytes(index + 6, header.array)      // ...header fields...
-         .set8(index + 38, folder ? 0x10 : 0) // is_dir flag
-         .set32(index + 42, offset)           // file offset
-         .bytes(index + 46, name)             // filename
-      index += 46 + name.length
-    }
-    cdr.set32(index, 0x06054b50)             // signature
-       .set16(index + 8, this.files.length)  // № files per-segment
-       .set16(index + 10, this.files.length) // № files this segment
-       .set32(index + 12, length)            // central directory length
-       .set32(index + 16, this.offset)       // file-offset of directory
-
-    // concatenated zipfile data
-    let output = new Uint8Array(this.offset + cdr.size),
-        cursor = 0;
-
-    for (var {payload} of this.files){
-      output.set(payload.array, cursor)
-      cursor += payload.size
-    }
-    output.set(cdr.array, cursor)
-
-    return output
-  }
-
-  get blob(){
-    return new Blob([this.toBuffer()], {type:"application/zip"})
-  }
-}
-
-
 //
 // Browser helpers for converting canvas elements to blobs/buffers/files/zips
 //
@@ -241,16 +101,23 @@ const asDownload = async (canvas, mime, quality, matte, filename) => {
 }
 
 const asZipDownload = async (pages, mime, quality, matte, archive, pattern, padding) => {
-  let filenames = i => pattern.replace('{}', String(i+1).padStart(padding, '0')),
-      folder = basename(archive, '.zip') || 'archive',
-      zip = new Zip(folder)
-
-  await Promise.all(pages.map(async (page, i) => {
-    let filename = filenames(i) // serialize filename(s) before awaiting
-    await zip.add(filename, await asBlob(page, mime, quality, matte))
-  }))
-
-  _download(`${folder}.zip`, zip.blob)
+  await import("jszip").then(async ({default:JSZip}) => {
+    let filenames = i => pattern.replace('{}', String(i+1).padStart(padding, '0')),
+        zip = new JSZip(),
+        folder = basename(archive, '.zip') || 'archive',
+        payload = zip.folder(folder)
+
+    await Promise.all(pages.map(async (page, i) => {
+      let filename = filenames(i) // serialize filename(s) before awaiting
+      payload.file(filename, await asBlob(page, mime, quality, matte))
+    }))
+
+    zip.generateAsync({type:"blob"})
+      .then(content => _download(`${folder}.zip`, content))
+  })
+  .catch(() => {
+    console.log("Multi-page downloads require JSZip to be bundled: https://www.npmjs.com/package/jszip")
+  })
 }
 
 const _download = (filename, blob) => {
@@ -318,11 +185,18 @@ class Format{
 // Validation of the options dict shared by the Canvas saveAs, toBuffer, and toDataURL methods
 //
 
-import {basename, extname} from 'path'
+function basename(str, ext) {
+    let stub = str.substring(str.lastIndexOf('/') + 1)
+    return ext && stub.endsWith(ext) ? stub.slice(0, -ext.length) : stub
+}
+
+function extname(str){
+  return str.substring(str.lastIndexOf('.'))
+}
 
 function exportOptions(pages, {filename='', extension='', format, page, quality, matte, density, archive}={}){
   var {fromMime, toMime, expected} = new Format(),
-      archive = archive || 'canvas',
+      archive = ''+(archive || 'canvas'),
       ext = format || extension.replace(/@\d+x$/i,'') || extname(filename),
       format = fromMime(toMime(ext) || ext),
       mime = toMime(format),