https://github.com/vectojs/vectojs
Canvas-native UI runtime with a Virtual Math Tree, semantic accessibility projection, WebGL/WebGPU backends, and agent-drivable controls.
https://github.com/vectojs/vectojs
a11y accessibility ai-agents canvas high-performance-ui runtime scene-graph semantic-ui threejs typescript webgl webgpu
Last synced: 12 days ago
JSON representation
Canvas-native UI runtime with a Virtual Math Tree, semantic accessibility projection, WebGL/WebGPU backends, and agent-drivable controls.
- Host: GitHub
- URL: https://github.com/vectojs/vectojs
- Owner: vectojs
- License: mit
- Created: 2026-06-25T11:14:26.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-07-25T20:53:48.000Z (14 days ago)
- Last Synced: 2026-07-25T21:10:03.931Z (14 days ago)
- Topics: a11y, accessibility, ai-agents, canvas, high-performance-ui, runtime, scene-graph, semantic-ui, threejs, typescript, webgl, webgpu
- Language: TypeScript
- Homepage: https://vectojs.org
- Size: 68.3 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
VectoJS
A canvas-native UI runtime: render like a scene engine, remain operable like the DOM.
VectoJS draws a scene graph onto one ``. Layout, hit-testing, animation, text flow, and
render scheduling operate on a Virtual Math Tree (VMT), while interactive entities project a thin
semantic DOM layer for accessibility and automation.
This is not an ECS and it does not claim allocation-free rendering. It is a retained-mode rendering
runtime for interfaces whose visual or interactive complexity is a poor fit for one DOM element per
shape, glyph, point, or row.
[Documentation](https://vectojs.org/learn/introduction/) ·
[Live demos](https://vectojs.org/demos/) ·
[Component reference](https://vectojs.org/reference/ui-components/) ·
[Issues](https://github.com/vectojs/vectojs/issues)
## Why VectoJS
- **Canvas-native visuals** — Canvas 2D is the default renderer; WebGL point batching and WebGPU
compute paths cover high-volume workloads.
- **Semantic projection** — buttons, links, inputs, checkboxes, sliders, and other controls expose
role/name/state through transparent DOM counterparts.
- **Real browser input** — `Input` and `TextArea` mirror native controls, preserving IME composition,
selection, clipboard, undo, and automation APIs.
- **Mathematical interaction** — transforms, bounds, spatial hashing, event capture/bubble, clipping,
and hit-testing live in one coordinate model.
- **Deterministic rendering tools** — on-demand redraw, fixed-step `Scene.step()`, and the video
exporter support tests, simulations, and offline capture.
- **Framework-neutral** — mount a canvas from React, Vue, Svelte, vanilla TypeScript, or a Three.js
scene; VectoJS does not own your application state.
## Packages
| Package | Purpose |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| [`@vectojs/core`](./packages/core) | Scene/Entity runtime, events, hit-testing, accessibility projection, Canvas/WebGL/WebGPU support; re-exports the engines below |
| [`@vectojs/text`](./packages/text) | Standalone text-shaping primitives: BiDi, Arabic shaping, CSS-parity typography, MSDF fonts, prepared content grids |
| [`@vectojs/layout`](./packages/layout) | Standalone layout engine: line breaking, BiDi-aware inline layout, exclusion flow, off-thread layout worker |
| [`@vectojs/math`](./packages/math) | Standalone spatial/physics math: spatial hash grid broad-phase and spring physics |
| [`@vectojs/animation`](./packages/animation) | Standalone easing library plus tween and spring value drivers |
| [`@vectojs/ui`](./packages/ui) | Canvas-native layout, form, content, data, navigation, and overlay components |
| [`@vectojs/markdown`](./packages/markdown) | Markdown + TeX-math rendering entity (`Markdown`, `CodeBlock`) built on `@vectojs/ui`, with `marked` + MathJax |
| [`@vectojs/three`](./packages/three) | Project a VectoJS scene onto a Three.js texture and route raycast/XR input back into 2D |
| [`@vectojs/devtools`](./packages/devtools) | In-page Virtual Math Tree inspector: entity tree, click-to-pick, live geometry readout and nudging |
| [`@vectojs/graph3d`](./packages/graph3d) | 3D force-directed graph rendering on instanced Three.js, with an in-house dependency-free Barnes-Hut layout |
| [`@vectojs/video-exporter`](./packages/video-exporter) | Fixed-step Chromium + FFmpeg H.264 MP4 export for local modules or hosted scenes |
## Install
```bash
bun add @vectojs/core
bun add @vectojs/ui # optional high-level components
```
The packages are standard ESM/CJS npm packages and also work with npm, pnpm, and yarn.
## Quick start
```html
#app {
position: relative;
width: 100vw;
height: 100vh;
}
canvas {
display: block;
width: 100%;
height: 100%;
}
```
```ts
import { Scene } from '@vectojs/core';
import { Button, Input, Stack, Text, Toggle } from '@vectojs/ui';
const canvas = document.querySelector('#canvas')!;
const scene = new Scene(canvas, { maxFPS: 60 });
scene.renderMode = 'onDemand';
const panel = new Stack({ direction: 'vertical', gap: 14 });
panel.setPosition(40, 40);
panel.add(new Text('Runtime settings', { font: '700 24px Inter' }));
panel.add(new Input({ width: 280, placeholder: 'Project name' }));
panel.add(new Toggle({ checked: true, label: 'GPU acceleration' }));
panel.add(
new Button('Save', {
onClick: () => console.log('saved'),
}),
);
scene.add(panel);
scene.start();
window.addEventListener('resize', () => {
scene.resize(window.innerWidth, window.innerHeight);
});
// Release renderers, workers, observers, and projected DOM when unmounting.
// scene.destroy();
```
The visual controls are canvas-rendered. Their semantic counterparts remain discoverable:
```ts
await page.getByRole('textbox', { name: 'Project name' }).fill('Nexus');
await page.getByRole('button', { name: 'Save' }).click();
```
## Architecture
The DOM projection is deliberately not the visual renderer. It carries semantics and native input;
the canvas remains the source of visible pixels.
## Where it fits
Good candidates:
- infinite canvases, graphs, timelines, whiteboards, node editors;
- dense dashboards, traces, order books, virtualized data, streaming output;
- particle fields, simulations, educational/diagramming tools;
- 2D panels embedded in Three.js/WebXR;
- interfaces that need both canvas scale and role-based accessibility/automation.
Prefer ordinary HTML/CSS for document-first pages, SEO-heavy prose, native text selection, small
static forms, or applications that do not benefit from a retained scene graph.
## Render and interaction model
1. Add `Entity` instances to a `Scene`.
2. Layout resolves local boxes and transforms.
3. Dirty scenes render through the selected backend.
4. Pointer input is mapped into scene coordinates, spatially queried, then dispatched through
capture and bubble phases.
5. Interactive entities synchronize role/name/state and native input through the semantic layer.
Read the [core guide](https://vectojs.org/learn/core-scene/) for lifecycle and rendering, and
the [accessibility guide](https://vectojs.org/learn/accessibility/) before shipping controls.
## Devtools
`@vectojs/devtools` ships an in-page VMT inspector — a canvas-rendered panel (dogfooding
`@vectojs/ui`) with the live entity tree, click-to-pick, a selection highlight overlay, geometry
readouts, and arrow-key nudging:
```ts
import { attachDevtools } from '@vectojs/devtools';
const devtools = attachDevtools(scene);
// …
devtools.detach();
```
## Agent skills
The [vectojs-skills](https://github.com/vectojs/vectojs-skills) repository packages Claude/agent
skills that teach coding agents the VectoJS paradigm — most importantly
`vectojs-paradigm`, which replaces HTML/CSS instincts with scene-graph thinking and a
state-space debugging ladder (inspect numbers and `getA11yTree()` before reaching for
screenshots). Skills also cover the core runtime, responsive layout, UI/animation, performance,
Three.js embedding, and the video exporter. Install them into `.claude/skills` or
`.agents/skills` of any project that uses VectoJS.
## Demos
The separate [vectojs-website](https://github.com/vectojs/vectojs-website) repository hosts live,
source-available stress tests:
- large danmaku streams and WebGPU particle fields;
- streaming Markdown/chat rendering;
- a knowledge graph;
- a VectoJS panel embedded in a Three.js scene;
- game-style pointer and keyboard interaction.
Performance depends on renderer, entity shape, text, hardware, and workload. Use the checked-in
benchmarks instead of treating demo counts as universal guarantees.
## Development and verification
```bash
bun install
just verify # = just check + just test (the pre-push habit)
```
`just check` is the same gate CI runs: `oxfmt --check` (formatting authority),
`oxlint --deny-warnings`, `markdownlint-cli2`, and `actionlint`. Individual
recipes are available too — run `just --list` to see them all:
```bash
just fmt # format in place (oxfmt)
just test-pkg core # one package's unit tests
just wasm # build the Rust wasm core
just e2e # real-browser e2e (HiDPI + text projection)
```
Additional reproducible workloads:
```bash
bun run benchmark # real browser frame-time workloads
bun run compare:dom # CDP layout/style/heap comparison
bun run compare # text-layout comparison
```
The project is pre-1.0. Read package changelogs before upgrading and pin versions in production.
## License
[MIT](./LICENSE) © 2026 Xuepoo