Numera

An Excel-oriented, canvas-native local personal spreadsheet built with VectoJS.

Numera stress-tests VectoJS with a virtualized 10,000 × 100 spreadsheet. The visible sheet is one retained canvas entity, not a DOM table: every cell position, hit test, selection rectangle, and scroll offset is explicit numeric scene state. Document semantics come from the exact-pinned published @vectojs/numera-core package; this repository owns only the VectoJS UI/UX adapter.

Included core behavior

• sparse formula document with scalar/range dependencies and cycle detection;
• formulas with arithmetic, percent, exponentiation, text concatenation, and SUM, AVG/AVERAGE, MIN, MAX, COUNT, IF, and CONCAT;
• common numeric, logical, and recovery formulas: ABS, ROUND, ROUNDUP, ROUNDDOWN, AND, OR, NOT, and IFERROR;
• virtualized grid, fixed headers, scrolling, pointer-drag range selection, keyboard navigation (arrows, Shift, Home/End, Page, Ctrl/Command corners), and double-click/F2/typing editing;
• native IME, clipboard, selection, and undo support through VectoJS Input;
• browser-native selection, copy, and find for projected VectoJS status text, without overriding workbook clipboard shortcuts when no text is selected;
• external TSV copy/paste plus internal formula/format-aware range transfer, range clearing, and transactional undo/redo;
• Ctrl/Command+A selection of the sparse used range plus Ctrl/Command+X/C/V and Z/Y document shortcuts, without creating writes for blank cells;
• ordered multi-sheet workbooks with a canvas-native tab strip, stable sheet identities, creation, rename/delete interactions, and versioned local snapshot persistence with safe recovery;
• selection formatting for background/foreground, bold/italic, horizontal alignment, and number/currency/percent display, with Ctrl/Command+B/I and transactional undo/redo.
• versioned workbook JSON plus formula-preserving RFC 4180 CSV serialization primitives, with canvas JSON/CSV copy controls and CSV paste import, shared by the CLI and MCP adapters.
• Canvas-native Import and XLSX toolbar intentions backed by the exact published @vectojs/[email protected] adapter. Native file selection and download elements are transient browser I/O only; the visible toolbar, status feedback, workbook replacement, and VMT refresh stay Canvas-native.
• structural row and column insertion/deletion with sparse-format preservation, A1-style formula-reference rewriting, and transactional undo/redo. The Canvas toolbar reflows every command on narrow screens without hiding import or export paths, and each action is a keyboard-operable VMT button with a minimum 44px hit target.
• stable ascending/descending range sorting by the active column through @vectojs/[email protected], including formula translation, exact format movement, one-step undo, semantic toolbar actions, and Alt+Shift+Arrow shortcuts that reject conflicting Ctrl/Command combinations;
• sparse per-row and per-column logical sizes, Canvas header-edge resize gestures, and a selection fill handle. Gesture previews remain numeric VMT state; fill commits translate relative A1 references and copy exact formats through Numera Core rather than repeating raw strings in the view layer. Releasing the pointer creates one undoable document transaction.
• responsive container measurement and ?debug VMT inspection/audit.

The XLSX codec and visual DevTools panel are loaded only after their explicit actions. Normal startup consumes @vectojs/ui/input, @vectojs/ui/measure, and @vectojs/devtools/headless; a build-time budget prevents Markdown/MathJax or the inspector panel from leaking back into the interactive spreadsheet entry.

Numera intentionally excludes collaboration, cloud persistence, accounts, sharing, comments, permissions, and platform scripting. Microsoft Excel is the primary reference for local workbook and file behavior, without claiming exhaustive compatibility. numera-cli, numera-skills, and numera-mcp are independent published companion repositories over the same pure document APIs.

Development

bun install
just dev

Open http://localhost:2323/?debug to attach the VectoJS devtools panel. The app also exposes window.__app with its scene, model, app, and audit() function. In debug mode, debugTrace() returns the bounded devtools pointer/wheel/keyboard routing records. Prefer inspecting this state and auditScene(scene) before using screenshots.

Verify

just verify
just browser-verify
just browser-verify firefox
just browser-verify-all

Browser verification uses the dedicated port 24323 by default so it does not attach to or terminate an Agent's development server on 2323. The test server is never reused, and the just recipes run Playwright in deterministic CI mode with web-server tracing so its child server remains attached in non-interactive Agent shells. Set PLAYWRIGHT_PORT when a parallel worktree needs another isolated E2E port.

Deploy

The canonical application is https://numera-website.vectojs.org/. Its Cloudflare Pages project is numera-website; the fallback deployment URL is https://numera-website.pages.dev. With an authenticated Wrangler session:

just deploy

The deployment script streams Wrangler output, waits for the final Deployment complete! marker, and then exits instead of waiting indefinitely for Wrangler logs. An upload-only message is not treated as a completed Pages deployment. just deploy runs the local non-browser verification gates and build before invoking that script. just browser-verify defaults to Chromium and accepts a Playwright project such as firefox; just browser-verify-all runs the complete Chromium, Firefox, and WebKit matrix used by CI.

Repository family

This repository lives in the vectojs-native/numera/ forge family. The CLI, skills, MCP adapter, XLSX codec, and published core document library remain separate repositories/packages so they share the pure model layer rather than automate the canvas UI.

License

MIT © 2026 Xuepoo