Basic Usage
import { createStage } from '@vielzeug/stage';
const stage = createStage(canvas, {
width: canvas.clientWidth,
height: canvas.clientHeight,
dpr: window.devicePixelRatio,
layers: [
{ id: 'grid', paint: (ctx, { visibleRect }) => drawGrid(ctx, visibleRect) },
{ id: 'scene', paint: (ctx, { visibleRect }) => drawScene(ctx, visibleRect) },
{ id: 'overlay', paint: (ctx) => drawSelection(ctx) },
],
});Each layer paints into its own cached backing surface. The stage composites all surfaces onto the visible canvas in registration order whenever a frame is scheduled. Paint callbacks receive a context already transformed by dpr × matrix, so they draw in world units and can cull against frame.visibleRect.
Layers are fixed when the stage is created — the same in both render modes. Hide a layer by returning early from its paint and invalidating it. The stage sizes the canvas backing store; you own the canvas CSS size (set it via CSS or a ResizeObserver).
Driving the Transform
The stage takes a world→screen matrix in CSS pixels (it applies DPR itself). Pair it with an @vielzeug/atlas camera:
import { createCamera } from '@vielzeug/atlas';
const camera = createCamera({ maxZoom: 16, minZoom: 0.05 });
camera.subscribe(() => stage.setTransform(camera.matrix));
canvas.addEventListener('wheel', (event) => {
event.preventDefault();
camera.zoomAt({ x: event.offsetX, y: event.offsetY }, Math.exp(-event.deltaY * 0.0015));
});setTransform() invalidates every layer — the cached world-space surfaces are no longer valid at the new transform. Compositing stays cheap (one drawImage per layer); only the paint callbacks re-run.
Dirty Repaints
Invalidate the smallest unit that changed:
token.x += 10;
stage.invalidate('tokens'); // only the tokens layer repaints next frameInvalidations within one frame coalesce into a single scheduled frame. Call stage.render() to force a synchronous repaint (useful in tests).
Resize and DPR Changes
new ResizeObserver(([entry]) => {
stage.resize({ width: entry.contentRect.width, height: entry.contentRect.height }, window.devicePixelRatio);
}).observe(canvas.parentElement!);resize() resizes the canvas backing store and invalidates all layers; surfaces are reallocated at the new pixel size.
Exporting a PNG
const blob = await stage.toBlob();
await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);toBlob() flushes any pending repaint before rasterizing, so it always captures the current frame — no manual render() first. It throws StageUnsupportedError when the canvas cannot produce a blob — the stage never silently degrades.
For a crop or a higher resolution, pass region (world units) and scale (export pixels per world unit):
// Export the visible area at 2× the on-screen density.
const blob = await stage.toBlob({
region: stage.visibleRect,
scale: stage.dpr * cameraZoom * 2,
});The stage re-paints every layer into scratch surfaces against the region transform, so the cost is a full repaint rather than a blit of the cached composite; the live viewport and its caches are untouched. scale defaults to the current device pixels per world unit, and omitting region exports the visible rect. A non-positive or non-finite region/scale throws StageConfigError.
Testing with Injected Surfaces
Inject a fake surface factory and scheduler to unit-test paint behaviour without a GPU:
const frames = { queued: new Set<(t: number) => void>() };
const stage = createStage(fakeCanvas, {
createSurface: (w, h) => fakeSurface(w, h),
height: 200,
scheduler: {
cancelFrame: (id) => frames.queued.delete(id),
now: () => 0,
requestFrame: (cb) => {
frames.queued.add(cb);
return frames.queued.size;
},
},
width: 400,
});The default factory uses OffscreenCanvas when present, else a canvas from the document; in environments with neither, it throws StageUnsupportedError.
Worker Rendering
The @vielzeug/stage/worker subpath renders the composited canvas inside a Web Worker. The main thread transfers an OffscreenCanvas once and then drives the stage over an internal message protocol; painters live worker-side. A WorkerStage and a main-thread Stage share the StageController type, so code that only controls a stage works with either.
// main.ts
import { createWorkerStage } from '@vielzeug/stage/worker';
type Scene = Readonly<{ col: number; id: string; row: number; type: 'move' }>;
const worker = new Worker(new URL('./stage.worker.ts', import.meta.url), { type: 'module' });
const stage = createWorkerStage<Scene>(canvas, worker, {
height: 600,
width: 800,
});
// The creator owns the worker: terminate it when the stage is disposed.
stage.disposalSignal.addEventListener('abort', () => worker.terminate());
await stage.ready; // the worker created its stage
stage.setTransform([1, 0, 0, 1, 0, 0]);
stage.sendScene({ col: 3, id: 'hero', row: 2, type: 'move' });
const blob = await stage.toBlob({ type: 'image/png' }); // correlated round-trip
stage.dispose(); // also rejects any in-flight blob requests// stage.worker.ts
import { serveStage } from '@vielzeug/stage/worker';
serveStage<Scene>(self, () => ({
layers: [{ id: 'scene', paint: (ctx) => ctx.fillRect(0, 0, 800, 600) }],
onScene: (scene, stage) => {
applyMove(scene);
stage.invalidate('scene'); // the handler owns repaints
},
}));Notes:
- The worker owns its painters.
serveStage'ssetupreturns thelayers(and optionalonScene/onDisposehooks); the main thread never names layers. - The canvas transfer is one-shot:
createWorkerStagecallstransferControlToOffscreen()on construction. To go back to main-thread rendering, mount a fresh<canvas>element. toBlob()sends ablobcommand and resolves with the worker's response; requests are correlated by id and reject withStageDisposedErrorif the client is disposed while one is in flight.regionandscaleare forwarded verbatim and applied worker-side.sendScene(scene)forwards your typed payload to the worker'sonScene(scene, stage)hook — useful for mirroring model state (e.g. token moves) without shipping painters to the main thread. The handler decides which layers to invalidate; nothing repaints automatically.- Invalid size, DPR, or matrix input throws
StageConfigErroron the main thread, exactly likecreateStage. - Worker-side exceptions are reported through
reportError, the same path an uncaught main-thread paint error takes. The protocol version is checked once at the init/ready handshake; a stale cached worker rejectsreadywith aStageErrorand disposes the stage.
Best Practices
- Keep per-layer paint callbacks cheap and cull with
frame.visibleRect; the stage caches the result, so cost is paid once per invalidation, not per frame. - Put rarely-changing content (tile grids, backgrounds) on lower layers so pointer-driven changes only repaint upper layers.
- Dispose the stage when the view unmounts:
using stage = createStage(...)orstage.dispose(). Disposal cancels scheduled frames and releases every backing surface. - Treat
StageUnsupportedErroras a hard capability gap (feature-detect or surface it to the user); there is deliberately no fallback path. - In worker mode, invalidate only the layers a scene message changed —
onSceneruns on every forwarded payload.