VardUI architecture
Goals and their consequences
| Goal | Consequence in the design |
|---|---|
| AI writes the code right the first time | a small regular language; syntax close to Swift/Kotlin/TS, where models have strong priors; one form for each thing (name: value, no modifier chains) |
| errors get fixed without thinking | a diagnostic = file:line + the line of code + fix:; vard check --fix applies fixes to a fixed point; “habit” tables (VStack→Column, onPress→onTap, var→state, "a"+n→"a{n}") |
| debugging without screenshots | a semantic tree with @ids, diffs after actions, why for sizes, state, lints with a ready recipe |
| minimal tokens | compact output formats; the reference is generated from the same registry as the checks; MCP tools are stateless — a “session” is a replayable list of actions |
| performance | fine-grained reactivity: a view body runs once, then exactly the prop whose dependencies changed is updated; single-pass layout |
| extensibility | design systems = plain Vard views (std is written that way); native functions = extern fn, platform events = extern event; elements = registry entries |
| an ecosystem for agents | packages with a contract computed by the compiler (API, capabilities), enforced semver, migrations as fix:es, installation by exact names only, a static signed registry (packages) |
Layers
.vard ──► vard-lang ──────────────────────────► vard-runtime ───────────────► platform
lexer → parser (arena AST, reactive graph (signals, headless: PNG (tiny-skia)
error recovery) → linker → computed, effects, scopes) Android (Kotlin host, Canvas)
checker (bidirectional types, retained Node tree [plan] iOS / Web / Desktop:
fixes) flex layout + why tracing GPU renderer + native views
registry.rs — elements, props, inspect: tree/layout/state/lint for IME/maps/camera
tokens, habit aliases actions: tap/type/scroll/expect
vard-cli: check · run · test · doc · explain · new · mcp
add · install · update · search · info · api
pack · publish · bundle · registry (serve)
vard-pkg: vard.toml · semver · MVS · vard.lock · .vpk · registries + log
vard-lang
- Lexer — line breaks are separators (except inside
(/[and before continuation lines.x,&&,?,:). It catches;,===,@Stateand the like right away, with a fix. - Parser — recursive descent, the AST in flat arenas (
ExprId/UiId=u32), so the runtime keeps cheap indices in effects. Recovery at the line and declaration level: one run reports as many independent errors as possible; “unknown name” cascades after a syntax error are suppressed. - Checker — the expected type flows down:
.center,.primaryand lambda parameters are inferred without annotations. TheUnknowntype after an error is compatible with everything — no avalanche of secondary errors. When the fix is obvious (an alias or an edit distance), checking continues as if it were already applied — one iteration instead of several. - registry.rs — the single source of truth: elements, props and their types, enums,
color tokens, the type scale, alias tables.
vard docis generated from it too.
Packages: linking, API, capabilities (vard-lang)
- link.rs — namespaces without imports. Package files arrive with
@name/...paths, the graph comes fromvard.lock(or aLinkInfofrom the CLI, with migrations). Resolution order: own → direct dependencies → std. Conflicting package declarations are renamed topkg.Namebefore type checking, so the checker and the runtime work with unique names and know nothing about packages. ErrorsE0230–E0235; package migrations becomeE0234with a fix, and checking continues as if it were applied. - api.rs — the public API (canonical items, a diff classified as major/minor/patch) and
capabilities computed from the code with evidence (
secureGet @ file:line).
vard-pkg
The data and protocol layer of the package manager, with no TLS stack: a TOML subset with
diagnostics and fixes, semver, minimal version selection, vard.lock, deterministic .vpk,
registries (builtin — the embedded packages/, a directory, HTTP) with key pinning and
verification of the signed hash chain, and loading a project with its dependencies for the
compiler (self-healing: a stale lock is reinstalled).
vard-runtime
- Reactivity.
state→ Signal,letand view parameters → Computed (lazy, cached, auto-tracked), every dynamic prop → an Effect writing one field of one node;if/for→ structural effects. Ownership is a tree ofScopes: disposing a scope frees everything created inside (effects, nodes, signals). Effects run in creation order (parent before child), which rules out glitches. - Equality cut-offs at every level: a signal does not notify for the same value, a prop does not touch the node for the same value, unchanged props do not mark layout dirty; static props (literals, enums, lambdas) create no effects at all.
- Keyed
for. Reconciliation by thebykey; each row has its own value signal, so changing one item of a 3000-item list re-runs one row’s effects (measured: 7 actions over 3000 rows — 35 effect runs). - Values —
Rc+ copy-on-write (Rc::make_mut): copying is free, mutation never creates aliases. That makes the semantics predictable for a model. - Layout — constraints down, sizes up, one pass. CSS flex semantics (
align,justify,grow,gap). Every node remembers why it got its size on each axis —whyprints the chain. Line wrapping is cached by (font, width). - Inspection — the semantic tree (meaningless containers hidden, labels merged as in
accessibility), diffs, selectors
@id/#id/ text, lints,state. - Runtime errors do not crash the app: any problem → an
Rdiagnostic withfile:line, the value becomesnil. Nodes from std views point at the place where the app uses the view.
The native bridge
- The boundary is two declarations:
extern fn(app → platform) andextern event(platform → app;on name(...) [if cond] { }handlers live while the view is on screen). Only data crosses (structs, enums, lists, maps, optionals) and callbacksfn(T)for results that come “later”; the checker forbids everything else (E0317). - The format is JSON. Encoding is untyped, decoding follows the type declared in Vard
(struct fields by name, enums by variant name, defaults for missing fields). So one native
function serves any app type:
firestoreGet*in thefirebasepackage returns a JSON document, and Vard turns it into aProfileorNotestruct — whatever the developer declared. - Callbacks — functions in arguments become
{"$callback": id}; the host answers withcallback(id, json, keep). A closure created inside a handler pins the temporary scopes it captured — they outlive the call until the platform answers. A callback of a view that has already left the screen is dropped silently. - The std platform (
std.vard): permissions,pref/prefGet,secure*(Keychain/Keystore), push and notifications,setColorScheme,openUrl,haptic, eventsappear/back/appResume/appPause/deepLink/push*, globalssafeArea,keyboardHeight,backProgress,isDark,screenWidth. - Headless —
Simin the runtime plays the platform deterministically: real in-memory prefs/secure storage, the permission dialog answers what the test said, push/back/insets are injected by actions,restartmodels a cold start. User externs answer with amockvalue or staypendinguntilresolve/send; packages’[sim]sets defaults. pref— state the runtime persists through the same boundary (prefGet/prefSetwith the keyvard.pref.<name>), one signal per name for the whole app.- Edge-to-edge and back — the host always draws under the system bars and passes the
insets;
safeAreaadds them to padding. If the code never mentionssafeArea, the runtime pads the root itself (a static flag from the checker).on back if condtells the host whether the app intercepts back (a flag in the frame header) — that decides whether Android shows the system predictive animation or hands the gesture progress to the app. - Text on devices — the core measures the platform font through the host’s
TextMeasurer(AndroidPaint.measureText), project fonts (fonts/) with the same file through fontdue. Line breaks and alignment on screen match what the layout computed.
vard-cli and MCP
Thin commands over the libraries. pkg.rs holds the package commands and the publish
gate (shared by vard publish and the registry server); server.rs is the registry’s HTTP
hosting. The MCP server (JSON-RPC over stdio) is stateless: vard_run mounts the app from
scratch each time and replays the actions — 50–100 ms, deterministic, nothing to go stale
between calls.
The debugging model for AI
vard check→ errors with fixes. 2.vard run --do "tree"→ the screen as text.- Actions print only the changes. 4.
why/layoutgive the numbers and the rule that made the size. 5. Lints describe the problem and the recipe. 6. A screenshot — only to judge visual design.
Roadmap
This version is a reference implementation of the core and tooling. For production on devices:
- Native shells. The Rust core builds as a
cdylib/staticlib; Android — a Kotlin host (JNI), iOS — a Swift host (C ABI). The runtime emits a buffer of tree mutation commands (create/set/insert/remove), the host applies them per frame. Done:crates/vard-ffi(C ABI + JNI) andplatforms/android(the:vardlibrary withVardActivity, the:appshell, thefirebasepackage’s native module). The host gets the whole frame — a flat list of draw records (format v2: shadows, gradients, per-corner radii, fonts, transforms,crates/vard-ffi/src/frame.rs); hit-testing andonTapbubbling stay in the core,Inputis a nativeEditTextover the Canvas. A mutation buffer instead of the full frame is the next step. - Rendering. The main path is our own GPU renderer (wgpu/Skia class) over the existing tree and layout: pixel-identical arbitrary designs and predictable performance. Native platform views are embedded where integration matters: text input with IME, maps, WebView, camera, video. Text shaping — HarfBuzz class with system fonts.
- Execution. The AST interpreter is the dev engine (instant start, hot reload). For release — compilation to a compact register bytecode or AOT to Rust; type checks are already static, so runtime checks go away.
- Native modules. Done:
extern fnwith callbacks,extern event+on, the std platform (permissions, push, prefs, secure storage, back, insets),vard bindings --kotlinand--swift(the Swift output is type-checked byswiftcin CI), self-registering module libraries, Firebase as a package with a native module, automatic inclusion of packages’ native modules in the Android build. Next:async/awaitsugar over callbacks. - Language. Done:
Map,pref,Grid, wrap, shadows/gradients/fonts, localized text (stringstables,t(), thelocaleglobal — checked at compile time). Next: navigation as a built-in element (today a stack +on backpattern), animations (animate:on props — interpolation in the effect layer without re-running logic; needs a frame clock from the host), gestures, virtualized long lists, image caching. - Accessibility. The semantic tree exists — mapping it to TalkBack/VoiceOver.
- On-device inspection. Done: the action protocol over TCP (
vard run --device), a listener invard-ffithat runs scripts on the UI thread, enabled in debuggable Android builds. Next: adeviceparameter for the MCP tools. - Packages. Done: vard.toml/vard.lock, MVS, the namespace linker, API and capabilities
from the compiler, enforced semver, migrations, the publish gate, a static signed registry,
vard registry serve,vard bundlewith the native fingerprint, git sources, enum/field migrations, behavioral checks with the previous version’s tests, quarantine and provenance, signed key rotation, a web page per registry, the public registry, signed OTA channels with on-device verification (vard ota). Next: the OTA download loop in the hosts, Merkle inclusion proofs, Sigstore attestations (see the package overview).