Version v26.11.26 Size 2.3 KB gzip
Why Stage?
A requestAnimationFrame loop that redraws everything every frame falls over once a canvas has more than a handful of layers: backgrounds, tiles, tokens, and overlays all repaint even when one token moved. Stage gives you a retained-mode alternative as a headless engine: every layer owns a cached backing surface, only dirty layers repaint, and the composite is one drawImage per layer. It handles DPR scaling, world-space transforms (pair it with @vielzeug/atlas cameras), and PNG export — with injectable surfaces and schedulers so the whole thing is unit-testable without a GPU.
Installation
sh
pnpm add @vielzeug/stagesh
npm install @vielzeug/stagesh
yarn add @vielzeug/stageQuick Start
ts
import { createStage } from '@vielzeug/stage';
const stage = createStage(canvas, {
dpr: window.devicePixelRatio,
height: 600,
layers: [
{ id: 'grid', paint: (ctx, { visibleRect }) => drawGrid(ctx, visibleRect) },
{ id: 'tokens', paint: (ctx) => drawTokens(ctx) },
],
width: 800,
});
stage.setTransform([2, 0, 0, 2, 40, 10]); // world→screen; DPR applied on top
token.x += 10;
stage.invalidate('tokens'); // only the tokens layer repaintsFeatures
createStage(): layered retained-mode renderer with cached per-layer surfaces- Dirty repaints: invalidate one layer or all; frames coalesce via an injectable scheduler
- DPR-aware transforms: paint in world units, the stage scales by
dpr × matrix StageController: one control type shared by main-thread and worker stagestoBlob(): PNG export of the composited canvas, flushing pending frames, with optional world-spaceregion/scalere-render and typed unsupported-capability errors- Injectable surfaces:
createSurfacefactory for tests andOffscreenCanvasworkers @vielzeug/stage/worker: worker-rendered stages via a transferredOffscreenCanvasand a typed scene channel