# @visant/psd-engine

> Isomorphic PSD mockup compositor — ag-psd tree → canvas (perspective warp, blend modes, raster masks, linked smart objects) + Scene Packages for client-side render.

Latest version **0.2.5** (published 2026-08-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @visant/psd-engine
pnpm add @visant/psd-engine
yarn add @visant/psd-engine
bun add @visant/psd-engine
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.5 |
| Published | 2026-08-11 |
| First published | 2026-06-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 231.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Visant Labs |
| Maintainers | pejaques |
| Keywords | psd, ag-psd, mockup, canvas, compositor, smart-object, perspective-warp |

## Links

- npm: https://www.npmjs.com/package/@visant/psd-engine
- Repository: https://github.com/pedrojaques99/visantlabs-os
- Homepage: https://github.com/pedrojaques99/visantlabs-os#readme
- Issues: https://github.com/pedrojaques99/visantlabs-os/issues
- npm.io page: https://npm.io/package/@visant/psd-engine

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [@crvouga/mockingbird-service-junction](https://npm.io/package/@crvouga/mockingbird-service-junction.md) — 0 weekly downloads
- [@crvouga/mockingbird-service-medplum](https://npm.io/package/@crvouga/mockingbird-service-medplum.md) — 0 weekly downloads
- [@crvouga/mockingbird-service-genebygene](https://npm.io/package/@crvouga/mockingbird-service-genebygene.md) — 0 weekly downloads

## Recent versions

- 0.2.5 (latest) — 2026-08-11
- 0.2.4 — 2026-08-11
- 0.2.3 — 2026-08-11
- 0.2.2 — 2026-08-11
- 0.2.1 — 2026-08-11
- 0.2.0 — 2026-08-10
- 0.1.0 — 2026-06-12

## README

# @visant/psd-engine

Isomorphic PSD mockup compositor. Takes an [`ag-psd`](https://github.com/Agamnentzar/ag-psd) layer tree and composites it to a canvas — perspective warp, blend modes, raster masks, and linked smart objects — running identically on the server (node-canvas), in the browser (DOM canvas), or in a local CLI.

It powers the Visant Labs mockup render pipeline and the **Scene Package** format, which pre-processes a PSD once into compact geometry + flattened layer images so the per-art render is a trivial warp + blend on any canvas (no PSD shipped to the client, minimal RAM).

> The engine is a generic compositor. The value/secret is the PSD templates — which never ship inside this package.

## Install

```bash
npm i @visant/psd-engine
# server-side rendering also needs the optional peers:
npm i ag-psd canvas
```

`ag-psd` and `canvas` are **optional** peer dependencies. The engine core and `scene/render` never import them — you inject a canvas factory (`CreateCanvas`). Browser builds pull in nothing extra.

## Exports

| Entry                | Purpose                                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `.`                  | `composePsd`, `flattenLayers`, `replaceLinkedSmartObjects`, `perspectiveWarp`, `coverArtCanvas`, `BLEND_MAP`, `computeFaces`, constants, types |
| `./scene`            | `extractScene` (PSD tree → `SceneDoc` + layer canvases), `renderScene` (`SceneDoc` + art → canvas)                                             |
| `./adapters/node`    | `createNodeAdapter()` → `{ createCanvas, loadImage, toBuffer }`, `initializeAgPsdCanvas(agPsd)`                                                |
| `./adapters/browser` | `createCanvas`, `loadImage`, `toBlob`                                                                                                          |

## Server render (full PSD)

```ts
import { flattenLayers, replaceLinkedSmartObjects, composePsd } from '@visant/psd-engine';
import { createNodeAdapter, initializeAgPsdCanvas } from '@visant/psd-engine/adapters/node';
import * as agPsd from 'ag-psd';

const { createCanvas, loadImage, toBuffer } = await createNodeAdapter();
await initializeAgPsdCanvas(agPsd);

const psd = agPsd.readPsd(buffer, { skipThumbnail: true, skipCompositeImageData: true });
const allLayers = flattenLayers(psd.children);
const target = allLayers.find((l) => l.name === 'Design Here');
replaceLinkedSmartObjects(allLayers, target, await loadImage(artBuffer), createCanvas);
const out = toBuffer(composePsd(psd, createCanvas), 'image/png');
```

## Scene Package

```ts
import { extractScene, renderScene } from '@visant/psd-engine/scene';

// Once per PSD (server, node adapter):
const { doc, assets } = extractScene(psd, createCanvas);
// → upload `assets` (canvases) + persist `doc` (SceneDoc JSON)

// Per render (browser or node):
const out = renderScene(doc, loadedAssets, { [faceKey]: artImage }, createCanvas);
```

`doc.warnings` flags blend modes the Canvas-2D mapping can't reproduce 1:1 — a hint to fall back to the full server compose.

## License

MIT

---
_Source: https://npm.io/package/@visant/psd-engine · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._