Architecture Overview

⚠️ Work in Progress: Vize is under active development and is not yet ready for production use. Internal architecture may change as the project evolves.

Vize is built as a modular Rust workspace where each crate handles a specific concern. The architecture is organized into reusable lanes that carry Vue SFC source through parsing, analysis, and compilation stages.

Project Relationship Map

The repository is organized like a studio: user-facing surfaces enter through JavaScript packages, the shared Rust core shapes Vue source, and specialized tools reuse the same parser and semantic model rather than each keeping a private copy of the language.

This relationship map is about ownership and reuse, not every call edge. The important invariant is that parser, AST, and semantic analysis stay shared, while the compiler backends and developer tools remain replaceable workshops around that shared language model.

Lanes

Stage Details

1. Source — A .vue file containing <template>, <script>, and <style> blocks

2. Armature (Parser) — Tokenizes the raw source into a stream of tokens, then parses them into a structured AST. The tokenizer handles Vue-specific syntax: directives (v-if, v-for, v-bind), expression interpolation ({{ }}), and SFC block boundaries.

3. Relief (AST) — The intermediate representation. All downstream stages operate on this shared AST, eliminating redundant parsing.

4. Croquis (Semantic Analysis) — Resolves template expressions, tracks variable scopes, detects binding types (setup, data, props, inject), and validates expression correctness. Uses OXC for JavaScript/TypeScript AST parsing.

5. Atelier (Compilation) — Transforms the analyzed AST into JavaScript output. Three backends serve different targets:

   • VDOM (vize_atelier_dom) — createVNode/h calls with patch flag optimization and static hoisting

   • Vapor (vize_atelier_vapor) — Fine-grained reactive code with direct DOM manipulation (no VDOM)

   • SSR (vize_atelier_ssr) — String concatenation with hydration markers

6. Output — Generated JavaScript code with source maps

Tool Lanes

Beyond compilation, Vize provides additional tools that reuse the same parsing and analysis infrastructure:

Because all tools share the same parser and AST, they have a consistent understanding of your code. A lint rule in Patina operates on the same AST nodes as the compiler in Atelier — there's no risk of parser disagreement.

For type checking, vize_canon adds one more step: it generates virtual TypeScript from Vue SFCs and asks Corsa project sessions from corsa-bind for native diagnostics, then maps those results back onto the original files.

The implementation workflow is documented in Language Engineering Practices, which maps parser, compiler, analyzer, type-checker, formatter, LSP, and release changes to the fixture, snapshot, parity, benchmark, and readiness evidence expected for review.

Crate Responsibilities

The gallery UI and dev-server integration for Musea live in the JavaScript package @vizejs/vite-plugin-musea; the Rust crate focuses on the parsing and generation core.

Naming Convention

Vize crates are named after art and sculpture terminology, reflecting how each component shapes and transforms Vue code. This naming system is more than aesthetic — it encodes the role and relationships between crates. See Philosophy for the full rationale.

Why Art Terminology?

The analogy between software compilation and artistic creation is surprisingly deep:

• A parser (Armature) provides the internal skeleton — the structure that everything else builds upon, just as a sculptor's armature supports the clay

• Semantic analysis (Croquis) is like a quick sketch — it captures the essential meaning without committing to a final form

• The compiler (Atelier) is a workshop where raw material is transformed into a finished work

• The AST (Relief) is a projection — it gives three-dimensional structure to what was originally flat text

• Bindings (Vitrine) are a glass display case — they let you see and interact with the work inside without directly touching it

• The linter (Patina) examines the surface finish — finding imperfections that affect the overall quality

• The formatter (Glyph) ensures consistent proportions — like a typographer carving letterforms with precise spacing

This naming convention makes the crate hierarchy intuitive: when you see vize_atelier_dom, you immediately understand it is a workshop that produces VDOM output.

External Dependencies

Vize integrates with the broader Rust ecosystem for specialized tasks: