# Paper.js — The Swiss Army Knife of Vector Graphics Scripting

> An open-source vector graphics scripting framework that runs on top of the HTML5 Canvas, offering a clean scene graph, powerful path manipulation, and PaperScript for concise creative coding.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Paper.js — The Swiss Army Knife of Vector Graphics Scripting

## Quick Use
```bash
npm install paper
```
```javascript
import paper from 'paper';
paper.setup(document.getElementById('canvas'));
const circle = new paper.Path.Circle(new paper.Point(150, 150), 50);
circle.fillColor = 'teal';
paper.view.draw();
```

## Introduction
Paper.js is a vector graphics scripting framework built on the HTML5 Canvas. It provides a comprehensive, well-designed API for creating and manipulating vector graphics, with particular strength in path operations like boolean combinations, simplification, and smoothing.

## What Paper.js Does
- Creates and manipulates vector paths, shapes, compound paths, and raster images
- Performs boolean operations (unite, intersect, subtract, exclude) on paths
- Simplifies and smooths complex paths algorithmically
- Handles mouse and keyboard events with hit-testing against the scene graph
- Exports to SVG and imports SVG content as editable Paper.js items

## Architecture Overview
Paper.js implements a full scene graph with a Project containing Layers, Groups, and Items. Each Item carries transformation matrices, styles, and child relationships. The rendering pipeline traverses the scene graph each frame, applying transformations hierarchically. A dedicated path geometry engine handles cubic bezier math, curve-fitting, and boolean clipping operations using a Greiner-Hormann variant.

## Self-Hosting & Configuration
- Install via npm or include the paper-full.js script from CDN
- Initialize with paper.setup(canvas) to bind to an HTML5 canvas element
- Use PaperScript (optional) for operator overloading on points and sizes
- Configure view settings for frame rate, auto-update, and pixel ratio
- Runs in Node.js with node-canvas for headless SVG or raster export

## Key Features
- Path boolean operations for constructive geometry (union, difference, intersection)
- Curve and path simplification reduces point counts while preserving shape
- Symbols and symbol instances for efficient repeated pattern rendering
- Raster items with pixel manipulation for image processing within the scene graph
- Comprehensive event model with onFrame, onMouseDown, onMouseDrag handlers

## Comparison with Similar Tools
- **Fabric.js** — focused on interactive object manipulation; less path math and booleans
- **Rough.js** — sketch aesthetic only; no path operations or scene graph
- **Snap.svg** — SVG manipulation library; Paper.js renders to Canvas with SVG import/export
- **Two.js** — minimal 2D API across renderers; Paper.js has richer geometry tools
- **p5.js** — creative coding focused on immediate mode; Paper.js offers retained scene graph

## FAQ
**Q: Can Paper.js export to SVG?**
A: Yes. Call project.exportSVG() to get a full SVG representation of the current scene.

**Q: Does it work with React?**
A: Yes. Instantiate Paper.js on a canvas ref in useEffect and manage scope lifecycle manually.

**Q: What is PaperScript?**
A: A thin scripting extension that enables operator overloading (e.g., point1 + point2) for cleaner math syntax. Plain JavaScript works without it.

**Q: How does performance scale?**
A: Paper.js handles thousands of path items efficiently. For tens of thousands of simple shapes, consider switching to a WebGL renderer.

## Sources
- https://github.com/paperjs/paper.js
- http://paperjs.org/reference/

---
Source: https://tokrepo.com/en/workflows/paper-js-swiss-army-knife-vector-graphics-scripting-6f0983fb
Author: Script Depot