Version v26.11.26 Size 5.8 KB gzip Dependencies Zero dependencies
Why Atlas?
Every infinite canvas re-implements the same three things badly: a camera that keeps the point under your cursor fixed while zooming, a hit-test that stops being O(n) once the scene grows, and selection and snapping math for moving rects. Atlas ships them as pure, headless primitives: a viewport-centred camera with anchor-preserving transforms and injectable animation scheduling, matrix/rect math, exact polygon narrow-phase, and a dynamic R-tree for O(log n) queries.
// Before
// Hand-rolled transform stacks, linear scans on every pointermove, and
// selection boxes that drift while zooming.
// After
import { createCamera, createSpatialIndex } from '@vielzeug/atlas';
const camera = createCamera();
camera.zoomAt({ x: 400, y: 300 }, 1.2); // world point under (400,300) stays put
const index = createSpatialIndex();
index.set('shape-1', { height: 40, width: 60, x: 12, y: 8 });
const hits = index.queryRect(camera.visibleRect); // viewport culling, returns ids| Feature | Atlas | Ad-hoc math | Full scene libraries |
|---|---|---|---|
| Bundle size | 5.8 KB | n/a | Typically 20–100 kB |
| External dependencies | n/a | Varies | |
| Anchor-preserving zoom/rotate | Built in | Drifts | Yes |
| Dynamic R-tree hit-testing | Built in | O(n) scans | Yes |
| Headless: no DOM, canvas, or renderer | Varies | Usually coupled |
Use Atlas when you own the render loop and scene model but want correct, tested camera, geometry, and spatial-query math without writing it yourself.
Consider a full canvas engine when you want a retained scene graph, built-in rendering, and event routing wholesale instead of headless primitives.
Installation
pnpm add @vielzeug/atlasnpm install @vielzeug/atlasyarn add @vielzeug/atlasQuick Start
import { createCamera, createSpatialIndex } from '@vielzeug/atlas';
// state.x/y is the world point at the viewport centre
const camera = createCamera({ initial: { x: 0, y: 0, zoom: 1 } });
camera.resize({ height: 600, width: 800 });
camera.panBy(20, 0); // content follows the drag
camera.fitBounds({ height: 400, width: 600, x: -50, y: -50 }, { padding: 40 });
const index = createSpatialIndex();
index.set('a', { height: 10, width: 10, x: 0, y: 0 });
index.queryPoint({ x: 5, y: 5 }); // ['a']Features
createCamera(): viewport-centred state, pan, anchor-preserving zoom/rotate,fitBounds(), rotatedvisibleRect, andanimateTo()with an injectable frame schedulercreateSpatialIndex(): dynamic R-tree (Guttman quadratic split) withset/delete/get/queryRect/queryPointover ids- Matrix helpers:
multiply,invert,apply,translate,scale,rotate,around,scaleOf,toCssMatrixin Canvas2D element order - Rect math: union, closed-interval intersection, containment, inflation, and bounds-from-points
- Snapping:
snapRect()alignment/grid/equal-gap guides withkind-tagged targets, plus purealignRects()/distributeRects() - Narrow-phase geometry:
pointInPolygon,distanceToPolyline,pointNearPolygonfor exact stroke and polygon hit-testing @vielzeug/atlas/gridsubpath: square-tile and axial-hex coordinate math, viewport culling,computeFov/computeHexFovvisibility, three-state fog, grid topologies, andfindPath/reachablesearch- Frames:
frameMatrix()local→world placement,boundsOfFrame()world AABBs, andresizeRect()editor resize math with min and aspect locks AtlasError/AtlasConfigError: typed errors; the camera follows the Vielzeug disposal contract- Zero runtime dependencies, no DOM requirement: works in Node, Workers, and SSR