Skip to content
stage logoStageUtilities
Retained-mode 2D canvas stage engine with DPR-aware layers, dirty repaints, and PNG export
Version
v26.11.26
Size
2.3 KB gzip
Browserworker
createStageStageErrorStageConfigErrorStageDisposedErrorStageUnsupportedError

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/stage
sh
npm install @vielzeug/stage
sh
yarn add @vielzeug/stage

Quick 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 repaints

Features ​

  • 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 stages
  • toBlob(): PNG export of the composited canvas, flushing pending frames, with optional world-space region/scale re-render and typed unsupported-capability errors
  • Injectable surfaces: createSurface factory for tests and OffscreenCanvas workers
  • @vielzeug/stage/worker: worker-rendered stages via a transferred OffscreenCanvas and a typed scene channel

Documentation ​

See Also ​

  • Atlas: cameras, spatial index, and tile grids that feed Stage transforms.
  • Gesture: pointer drag, pinch, and wheel recognition.