@napi-rs/canvas 0.1.83 → 0.1.85

package/README.md

@@ -298,6 +298,92 @@ path.simplify().toSVGString()
 // => "M89.005 3.818L2.933 89.89Q1.526 91.296 0.765 93.134Q0.004 94.972 0.004 96.961Q0.004 98.95 0.765 100.788Q1.526 102.625 2.933 104.032Q4.339 105.439 6.177 106.2Q8.015 106.961 10.004 106.961Q11.993 106.961 13.831 106.2Q15.668 105.439 17.075 104.032L96.076 25.031L175.077 104.032Q176.484 105.439 178.322 106.2Q180.159 106.961 182.148 106.961Q184.138 106.961 185.975 106.2Q187.813 105.439 189.219 104.032Q190.626 102.625 191.387 100.788Q192.148 98.95 192.148 96.961Q192.148 94.972 191.387 93.134Q190.626 91.296 189.22 89.89L103.147 3.818Q101.741 2.411 99.903 1.65Q98.065 0.889 96.076 0.889Q94.087 0.889 92.249 1.65Q90.412 2.411 89.005 3.818Z"
 ```
 
+## Lottie Animation
+
+Render [Lottie](https://airbnb.io/lottie/) animations using Skia's [Skottie](https://skia.org/docs/user/modules/skottie/) module.
+
+### Load Animation
+
+```js
+const { LottieAnimation } = require('@napi-rs/canvas')
+
+// Load from file
+const animation = LottieAnimation.loadFromFile('animation.json')
+
+// Load from JSON string with resource path for external assets
+const animation = LottieAnimation.loadFromData(jsonString, {
+  resourcePath: '/path/to/assets',
+})
+```
+
+### Animation Properties
+
+```js
+animation.duration // Total duration in seconds
+animation.fps // Frames per second
+animation.frames // Total frame count
+animation.width // Animation width
+animation.height // Animation height
+animation.version // Lottie format version
+```
+
+### Playback Control
+
+```js
+animation.seekFrame(30) // Seek to frame 30
+animation.seek(1.5) // Seek to 1.5 seconds
+```
+
+### Render to Canvas
+
+```js
+const { createCanvas, LottieAnimation } = require('@napi-rs/canvas')
+
+const animation = LottieAnimation.loadFromFile('animation.json')
+const canvas = createCanvas(animation.width, animation.height)
+const ctx = canvas.getContext('2d')
+
+// Render at original size
+animation.render(ctx)
+
+// Render with custom destination rect
+animation.render(ctx, { x: 0, y: 0, width: 800, height: 600 })
+```
+
+### Supported Features
+
+- **Embedded images** - Base64-encoded images (`data:image/png;base64,...`)
+- **Embedded fonts** - Vector glyph paths for text rendering without system fonts
+- **External assets** - Load images from `resourcePath` directory
+- **dotLottie format** - Extract `.lottie` ZIP files at runtime (see example)
+
+### Example: Encode Lottie to Video
+
+See [`example/lottie-to-video.ts`](./example/lottie-to-video.ts) for encoding Lottie animations to MP4 using [`@napi-rs/webcodecs`](https://github.com/Brooooooklyn/webcodecs-node).
+
+```js
+import { createCanvas, LottieAnimation } from '@napi-rs/canvas'
+import {
+  VideoEncoder,
+  VideoFrame,
+  Mp4Muxer,
+  type EncodedVideoChunk,
+  type EncodedVideoChunkMetadata,
+} from '@napi-rs/webcodecs'
+
+const animation = LottieAnimation.loadFromFile('animation.json')
+const canvas = createCanvas(animation.width, animation.height)
+const ctx = canvas.getContext('2d')
+
+for (let frame = 0; frame < animation.frames; frame++) {
+  animation.seekFrame(frame)
+  ctx.fillStyle = '#ffffff'
+  ctx.fillRect(0, 0, canvas.width, canvas.height)
+  animation.render(ctx)
+  // Encode frame to video...
+}
+```
+
 # [Example](./example/tiger.js)
 
 > The tiger.json was serialized from [gojs/samples/tiger](https://github.com/NorthwoodsSoftware/GoJS/blob/master/samples/tiger.html)

package/index.d.ts

@@ -619,6 +619,121 @@ export interface AvifConfig {
   /** set to '4:2:0' to use chroma subsampling, default '4:4:4' */
   chromaSubsampling?: ChromaSubsampling
 }
+
+/** GIF encoding configuration for single-frame encoding */
+export interface GifConfig {
+  /**
+   * Quality for NeuQuant color quantization (1-30, lower = slower but better quality)
+   * @default 10
+   */
+  quality?: number
+}
+
+/** Configuration for the GIF encoder (animated GIFs) */
+export interface GifEncoderConfig {
+  /**
+   * Loop count: 0 = infinite loop, positive number = finite loops
+   * @default 0 (infinite)
+   */
+  repeat?: number
+  /**
+   * Quality for NeuQuant color quantization (1-30, lower = slower but better quality)
+   * @default 10
+   */
+  quality?: number
+}
+
+/** Configuration for individual GIF frames */
+export interface GifFrameConfig {
+  /**
+   * Frame delay in milliseconds
+   * @default 100
+   */
+  delay?: number
+  /** Disposal method for this frame */
+  disposal?: GifDisposal
+  /** Transparent color index (0-255), if the frame has transparency */
+  transparent?: number
+  /** X offset of this frame within the canvas */
+  left?: number
+  /** Y offset of this frame within the canvas */
+  top?: number
+}
+
+/** GIF frame disposal method */
+export enum GifDisposal {
+  /** Keep the frame visible (default) */
+  Keep = 0,
+  /** Clear the frame area to the background color */
+  Background = 1,
+  /** Restore to the previous frame */
+  Previous = 2,
+}
+
+/**
+ * GIF Encoder for creating animated GIFs.
+ * Implements `Disposable` interface for use with the `using` keyword (ES2024).
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const encoder = new GifEncoder(100, 100, { repeat: 0, quality: 10 });
+ * encoder.addFrame(rgbaData, 100, 100, { delay: 100 });
+ * encoder.addFrame(rgbaData2, 100, 100, { delay: 100 });
+ * const buffer = encoder.finish();
+ *
+ * // With `using` keyword (automatic cleanup)
+ * {
+ *   using encoder = new GifEncoder(100, 100);
+ *   encoder.addFrame(frame1, 100, 100, { delay: 100 });
+ *   const buffer = encoder.finish();
+ * } // encoder automatically disposed
+ * ```
+ */
+export class GifEncoder implements Disposable {
+  /**
+   * Create a new GIF encoder with the specified dimensions
+   * @param width - Width of the GIF canvas in pixels
+   * @param height - Height of the GIF canvas in pixels
+   * @param config - Optional encoder configuration
+   */
+  constructor(width: number, height: number, config?: GifEncoderConfig)
+
+  /** Width of the GIF canvas */
+  readonly width: number
+  /** Height of the GIF canvas */
+  readonly height: number
+  /** Number of frames added so far */
+  readonly frameCount: number
+
+  /**
+   * Add a frame from RGBA pixel data
+   * @param data - RGBA pixel data (must be width * height * 4 bytes)
+   * @param width - Width of the frame in pixels
+   * @param height - Height of the frame in pixels
+   * @param config - Optional frame configuration
+   */
+  addFrame(data: Uint8Array, width: number, height: number, config?: GifFrameConfig): void
+
+  /**
+   * Finish encoding and return the GIF data.
+   * Clears all accumulated frames after encoding.
+   * @throws Error if no frames have been added
+   */
+  finish(): Buffer
+
+  /**
+   * Dispose of the encoder, clearing all accumulated frames without encoding.
+   * Called automatically when using the `using` keyword.
+   */
+  dispose(): void
+
+  /**
+   * Symbol.dispose implementation for ES2024 Explicit Resource Management.
+   * Allows using `using encoder = new GifEncoder(...)` syntax.
+   */
+  [Symbol.dispose](): void
+}
 /**
  * https://en.wikipedia.org/wiki/Chroma_subsampling#Types_of_sampling_and_subsampling
  * https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Video_concepts
@@ -676,24 +791,29 @@ export class Canvas {
   encodeSync(format: 'webp' | 'jpeg', quality?: number): Buffer
   encodeSync(format: 'png'): Buffer
   encodeSync(format: 'avif', cfg?: AvifConfig): Buffer
+  encodeSync(format: 'gif', quality?: number): Buffer
   encode(format: 'webp' | 'jpeg', quality?: number): Promise<Buffer>
   encode(format: 'png'): Promise<Buffer>
   encode(format: 'avif', cfg?: AvifConfig): Promise<Buffer>
+  encode(format: 'gif', quality?: number): Promise<Buffer>
   encodeStream(format: 'webp' | 'jpeg', quality?: number): ReadableStream<Buffer>
   encodeStream(format: 'png'): ReadableStream<Buffer>
   toBuffer(mime: 'image/png'): Buffer
   toBuffer(mime: 'image/jpeg' | 'image/webp', quality?: number): Buffer
   toBuffer(mime: 'image/avif', cfg?: AvifConfig): Buffer
+  toBuffer(mime: 'image/gif', quality?: number): Buffer
   // raw pixels
   data(): Buffer
   toDataURL(mime?: 'image/png'): string
   toDataURL(mime: 'image/jpeg' | 'image/webp', quality?: number): string
-  toDataURL(mime?: 'image/jpeg' | 'image/webp' | 'image/png', quality?: number): string
+  toDataURL(mime: 'image/gif', quality?: number): string
+  toDataURL(mime?: 'image/jpeg' | 'image/webp' | 'image/png' | 'image/gif', quality?: number): string
   toDataURL(mime?: 'image/avif', cfg?: AvifConfig): string
 
   toDataURLAsync(mime?: 'image/png'): Promise<string>
   toDataURLAsync(mime: 'image/jpeg' | 'image/webp', quality?: number): Promise<string>
-  toDataURLAsync(mime?: 'image/jpeg' | 'image/webp' | 'image/png', quality?: number): Promise<string>
+  toDataURLAsync(mime: 'image/gif', quality?: number): Promise<string>
+  toDataURLAsync(mime?: 'image/jpeg' | 'image/webp' | 'image/png' | 'image/gif', quality?: number): Promise<string>
   toDataURLAsync(mime?: 'image/avif', cfg?: AvifConfig): Promise<string>
 
   toBlob(callback: (blob: Blob | null) => void, mime?: string, quality?: number): void
@@ -837,3 +957,99 @@ export declare class PDFDocument {
   endPage(): void
   close(): Buffer
 }
+
+export interface LottieAnimationOptions {
+  /** Base path for resolving external resources (images, fonts) */
+  resourcePath?: string
+}
+
+export interface LottieRenderRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * Lottie animation class for loading and rendering Lottie JSON files.
+ *
+ * @example
+ * ```typescript
+ * import { LottieAnimation, createCanvas } from '@napi-rs/canvas'
+ *
+ * const animation = LottieAnimation.loadFromFile('./animation.json')
+ * const canvas = createCanvas(animation.width, animation.height)
+ * const ctx = canvas.getContext('2d')
+ *
+ * // Render frame 0
+ * animation.seekFrame(0)
+ * animation.render(ctx)
+ *
+ * // Save to PNG
+ * const buffer = canvas.toBuffer('image/png')
+ * ```
+ */
+export declare class LottieAnimation {
+  /**
+   * Load animation from JSON string or Buffer
+   * @param data - JSON string or Buffer containing Lottie animation data
+   * @param options - Optional configuration
+   */
+  static loadFromData(data: string | Buffer, options?: LottieAnimationOptions): LottieAnimation
+
+  /**
+   * Load animation from file path
+   * External assets are resolved relative to the file's directory
+   * @param path - Path to the Lottie JSON file
+   */
+  static loadFromFile(path: string): LottieAnimation
+
+  /** Animation duration in seconds */
+  readonly duration: number
+
+  /** Frame rate (frames per second) */
+  readonly fps: number
+
+  /** Total frame count */
+  readonly frames: number
+
+  /** Animation width in pixels */
+  readonly width: number
+
+  /** Animation height in pixels */
+  readonly height: number
+
+  /** Lottie format version string */
+  readonly version: string
+
+  /** Animation in-point (start frame) */
+  readonly inPoint: number
+
+  /** Animation out-point (end frame) */
+  readonly outPoint: number
+
+  /**
+   * Seek to normalized position
+   * @param t - Position between 0.0 (start) and 1.0 (end)
+   */
+  seek(t: number): void
+
+  /**
+   * Seek to specific frame index
+   * @param frame - Frame index (0 = first frame)
+   */
+  seekFrame(frame: number): void
+
+  /**
+   * Seek to specific time in seconds
+   * @param seconds - Time in seconds from start
+   */
+  seekTime(seconds: number): void
+
+  /**
+   * Render current frame to canvas context
+   * @param ctx - Canvas 2D rendering context
+   * @param dst - Optional destination rectangle for scaling/positioning
+   */
+  render(ctx: CanvasRenderingContext2D, dst?: LottieRenderRect): void
+}

package/index.js

@@ -17,12 +17,22 @@ const {
   StrokeCap,
   convertSVGTextToPath,
   PdfDocument,
+  GifEncoder,
+  GifDisposal,
+  LottieAnimation,
 } = require('./js-binding')
 
 const { DOMPoint, DOMMatrix, DOMRect } = require('./geometry')
 
 const loadImage = require('./load-image')
 
+// Add Symbol.dispose support for GifEncoder (ECMAScript 2024 Explicit Resource Management)
+if (GifEncoder && typeof Symbol.dispose !== 'undefined') {
+  GifEncoder.prototype[Symbol.dispose] = function () {
+    this.dispose()
+  }
+}
+
 const SvgExportFlag = {
   ConvertTextToPaths: 0x01,
   NoPrettyXML: 0x02,
@@ -178,4 +188,9 @@ module.exports = {
   CanvasElement,
   SVGCanvas,
   PDFDocument: PdfDocument,
+  // GIF encoding
+  GifEncoder,
+  GifDisposal,
+  // Lottie animation
+  LottieAnimation,
 }

package/js-binding.js

@@ -460,3 +460,5 @@ module.exports.PathOp = nativeBinding.PathOp
 module.exports.StrokeCap = nativeBinding.StrokeCap
 module.exports.StrokeJoin = nativeBinding.StrokeJoin
 module.exports.SvgExportFlag = nativeBinding.SvgExportFlag
+module.exports.GifEncoder = nativeBinding.GifEncoder
+module.exports.GifDisposal = nativeBinding.GifDisposal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/canvas",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "Canvas for Node.js with skia backend",
   "main": "index.js",
   "repository": {
@@ -37,6 +37,7 @@
       "x86_64-unknown-linux-gnu",
       "x86_64-apple-darwin",
       "x86_64-pc-windows-msvc",
+      "aarch64-pc-windows-msvc",
       "armv7-unknown-linux-gnueabihf",
       "x86_64-unknown-linux-musl",
       "aarch64-unknown-linux-gnu",
@@ -58,6 +59,7 @@
     "bench": "node --import @oxc-node/core/register benchmark/bench.ts",
     "build": "napi build --platform --release --js js-binding.js",
     "build:debug": "napi build --platform --js js-binding.js",
+    "example-lottie": "yarn oxnode ./example/lottie-to-video.ts",
     "format": "run-p format:source format:rs format:toml",
     "format:rs": "cargo fmt",
     "format:source": "prettier . -w",
@@ -76,8 +78,10 @@
     "@jimp/jpeg": "^0.22.12",
     "@jimp/png": "^0.22.12",
     "@napi-rs/cli": "^3.1.1",
+    "@napi-rs/webcodecs": "^1.1.0",
     "@octokit/rest": "^22.0.0",
-    "@oxc-node/core": "^0.0.34",
+    "@oxc-node/cli": "^0.0.35",
+    "@oxc-node/core": "^0.0.35",
     "@taplo/cli": "^0.7.0",
     "@types/lodash": "^4.17.17",
     "@types/node": "^24.0.0",
@@ -102,7 +106,7 @@
     "semver": "^7.7.2",
     "skia-canvas": "^3.0.0",
     "table": "^6.9.0",
-    "tinybench": "^5.0.0",
+    "tinybench": "^6.0.0",
     "typescript": "^5.8.3"
   },
   "lint-staged": {
@@ -140,17 +144,22 @@
     "singleQuote": true,
     "arrowParens": "always"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Brooooooklyn"
+  },
   "packageManager": "yarn@4.12.0",
   "optionalDependencies": {
-    "@napi-rs/canvas-linux-x64-gnu": "0.1.83",
-    "@napi-rs/canvas-darwin-x64": "0.1.83",
-    "@napi-rs/canvas-win32-x64-msvc": "0.1.83",
-    "@napi-rs/canvas-linux-arm-gnueabihf": "0.1.83",
-    "@napi-rs/canvas-linux-x64-musl": "0.1.83",
-    "@napi-rs/canvas-linux-arm64-gnu": "0.1.83",
-    "@napi-rs/canvas-linux-arm64-musl": "0.1.83",
-    "@napi-rs/canvas-darwin-arm64": "0.1.83",
-    "@napi-rs/canvas-android-arm64": "0.1.83",
-    "@napi-rs/canvas-linux-riscv64-gnu": "0.1.83"
+    "@napi-rs/canvas-linux-x64-gnu": "0.1.85",
+    "@napi-rs/canvas-darwin-x64": "0.1.85",
+    "@napi-rs/canvas-win32-x64-msvc": "0.1.85",
+    "@napi-rs/canvas-win32-arm64-msvc": "0.1.85",
+    "@napi-rs/canvas-linux-arm-gnueabihf": "0.1.85",
+    "@napi-rs/canvas-linux-x64-musl": "0.1.85",
+    "@napi-rs/canvas-linux-arm64-gnu": "0.1.85",
+    "@napi-rs/canvas-linux-arm64-musl": "0.1.85",
+    "@napi-rs/canvas-darwin-arm64": "0.1.85",
+    "@napi-rs/canvas-android-arm64": "0.1.85",
+    "@napi-rs/canvas-linux-riscv64-gnu": "0.1.85"
   }
 }