VardUI documentation
VardUI is a cross-platform UI framework whose primary “developer” is an LLM agent: the Vard language, a fine-grained reactive runtime, a headless platform simulator, tooling with machine-applicable fixes, and a package system designed for a world where a model adds dependencies and a person approves them.
These pages are for people. The references for agents are compiled into the vard binary
and printed by vard doc (sources in
knowledge/).
Start here
| Page | What it covers |
|---|---|
| Getting started | install, first project, the “edit → check → run → test” loop |
| Working with AI agents | how the AI-first approach works: AGENTS.md, skills, MCP, token budget |
Guide
| Page | What it covers |
|---|---|
| The Vard language | types, declarations, views, the UI tree, expressions, mutability, functions |
| UI: elements, layout, style | built-in elements, flex/grid, common props, tokens, themes, dark mode |
| Reactivity and execution model | signals/computed/effects, keyed lists, rules for pure rendering |
| Platform and native modules | lifecycle, back, insets, permissions, storage, push, extern fn/extern event |
| Testing and debugging | headless runs, the action language, .vtest, why, lints, the platform simulator |
| Tooling: CLI and MCP | every vard command, the MCP server, output formats |
| Diagnostics | E/W/R/L/P codes, how to read and fix them |
Packages, registries and delivery
| Page | What it covers |
|---|---|
| Package system overview | the idea and key decisions: a contract computed by the compiler |
| Using packages | vard search/add/update, vard.toml, vard.lock, namespaces, the capability policy |
| Writing a package | layout, manifest, AGENT.md, the example as proof, migrations, native code, publishing |
| Registries and hosting | protocol, file formats, vard registry serve, CDNs, registries in git, private registries |
| Delivery to devices | vard bundle, the native fingerprint, Android, over-the-air updates |
| Security model | threats (including LLM-specific ones) and defenses |
Platforms and architecture
| Page | What it covers |
|---|---|
| Architecture | layers, decisions, roadmap |
| Android shell | build, Gradle properties, native modules |
| ADRs | architecture decision records 0001–0007 |
Developing the framework
See CLAUDE.md (rules for agents working on the framework) and “Developing the framework itself” in the README.
Getting started
Install
Prebuilt binaries for Linux, macOS and Windows are on
GitHub Releases. The install scripts download
the latest one, verify its SHA-256 and put it into ~/.vard/bin:
curl -fsSL https://raw.githubusercontent.com/vardemin/vardui/master/install.sh | sh
irm https://raw.githubusercontent.com/vardemin/vardui/master/install.ps1 | iex
From source (Rust 1.98, pinned in rust-toolchain.toml; rustup fetches it automatically):
git clone https://github.com/vardemin/vardui.git
cd vardui
cargo build --release
The binary is vard (target/release/vard from source). Everything a person or an agent
needs — compiler, headless runtime, test runner, reference,
package manager, registry server and MCP server — is in this one file.
First project
vard new hello
hello/
app.vard the root view App
vard.toml manifest: app name, dependencies, policy
tests/smoke.vtest a scripted test
AGENTS.md, CLAUDE.md instructions for agents (the package list block updates itself)
.mcp.json the `vard mcp` server for Claude Code and other clients
.claude/skills/ skills vard-app, vard-debug, vard-native, vard-design, vard-packages
app.vard:
view App {
state count = 0
Column(padding: 24, gap: 16, justify: .center, align: .center, grow: 1) {
Text("Hello, Vard", style: .title)
Text("Tapped {count} times", color: .muted)
Button("Tap me", onTap: { count += 1 })
}
}
The development loop
The same for a person and for an agent; every step takes milliseconds and is deterministic.
cd hello
vard check --fix # types + machine fixes
vard run # the screen as text (semantic tree)
vard run --do 'tap "Tap me"; expect "Tapped 1 times"'
vard test # every tests/*.vtest
vard run prints the screen as a tree with ids:
> tree
screen 390x844 light
App @1
Text "Hello, Vard" @2
Text "Tapped 0 times" @3
Button "Tap me" @4
A mutating action prints only what changed:
> tap "Tap me"
~ Text "Tapped 1 times" @3
A compile error is a location, the line of code and a fix:
app.vard:2:3 error E0201: unknown element `VStack`
2 | VStack(gap: 8) {
fix: `VStack` -> `Column` (auto: vard check --fix)
Add a package
vard search tailwind
vard add tailwind
vard doc tailwind # the package's AGENT.md + the API generated by the compiler
After vard add the package’s public names are visible without imports:
TwButton("Save", onTap: save). More in Using packages.
Run on Android
cd platforms/android
./gradlew installDebug -Pvard.app=examples/todo
You need the Android SDK/NDK and cargo-ndk — see Android shell. The build
bundles the app and its packages (vard bundle) and includes the packages’ native modules
by itself.
Next
- The Vard language — the full language description.
- Testing and debugging — the action language and the platform simulator.
- Working with AI agents — how to set up an agent working on a project.
- Examples:
examples/—todo,patterns,native,showcase,firebase.
Working with AI agents
VardUI was designed around one question: what does each step of the “write → check → run → understand what went wrong” loop cost an agent — in tokens, in time, and in the probability of a mistake. Below is what the answer is made of and how to use it.
Principles
| Principle | How it is implemented |
|---|---|
| Write it right the first time | a small regular language, syntax close to Swift/Kotlin/TS, one form for each thing |
| Fix without thinking | every diagnostic is file:line, the line of code, fix:; vard check --fix applies fixes to a fixed point; “habit” tables (VStack → Column, onPress → onTap, "a" + n → "a{n}") |
| See without vision | a semantic tree ≈ 100 tokens; actions print diffs; why explains sizes; lints describe the recipe |
| Knowledge from one source | the reference is compiled into the binary and generated from the element registry — it cannot drift from the compiler |
| Determinism | headless runtime, bundled font, platform simulator, MVS for versions: same inputs, same result |
| A person decides outward-facing and risky steps | approving package capabilities and publishing are not available through MCP |
What an agent gets in a project
vard new creates:
AGENTS.md(andCLAUDE.md→@AGENTS.md) — the work loop, debugging rules, conventions, and a<!-- vard:packages -->block that the package manager keeps current;.claude/skills/—vard-app(screen patterns),vard-debug,vard-native,vard-design,vard-packages; packages’ skills are added on install as<package>-<skill>;.mcp.json— thevard mcpserver.
Token budget
| Operation | Cost |
|---|---|
the full language reference (vard doc) | ≈ 3k tokens, once per session |
the whole screen (tree) | ≈ 110 tokens (a screenshot: 450–1600) |
| the result of an action | ≈ 30 tokens: only the lines that changed |
vard check | ~20 ms; whatever is fixable is fixed without the model |
a package: one line in vard doc / vard doc NAME | ≈ 30 / ≤ 1500 tokens |
| a package update | an API diff + --fix instead of reading a changelog |
Recommended agent loop
- Once per session —
vard doc(orvard_doc). - Edit
.vard→vard check --fix→ fix the rest. vard run --do "…"— the screen and actions;whyfor sizes,state/logfor values.- A test for every feature and bug:
tests/*.vtest,vard test. - Need “library” functionality —
vard search→vard info→vard add→vard doc NAME. Never guess names; onP008, ask the user. - A screenshot — only to judge how it looks.
Why packages are built this way
The package system continues the same principles (overview):
- the compiler computes the contract — an agent does not need to trust a description or read code to know a package’s API and capabilities;
- installation never guesses — protection against hallucinated names;
- knowledge has a budget — AGENT.md ≤ 6 KB, the API is generated;
- updates are mechanical — package migrations become
fix:es; - a package runs headless —
[sim]and tests at publish time; - risk stays with a person — sensitive capabilities are approved in
vard.toml.
Working on the framework itself
Rules for agents changing VardUI are in
CLAUDE.md: where the single
sources of truth are (element registry, std, explain tables), what must be updated together
(knowledge, skills, examples), and how to verify (cargo test --workspace, vard test on
the examples and packages).
The Vard language
Vard is a declarative, statically typed language for user interfaces. Its syntax is close
to Swift/Kotlin/TypeScript (where models have strong priors), but there is one way to
write each thing: no modifier chains, no decorator annotations, no alternative syntaxes.
The full reference for agents is vard doc (≈ 3k tokens); this page says the same in more
detail, with the reasons.
Files and projects
- Sources are
*.vard. All files of the project directory (recursively, except hidden directories,target,build,node_modules) form one namespace: there are no imports. - The app’s root view is
view App. Without it,vard runmounts the last view declared in the project’s code. - Dependencies are declared in
vard.toml; their public names are visible without imports (rules: Using packages). - Statements end at the line break;
;is errorE0106with an auto-fix. Line breaks are allowed inside(/[and before continuation lines (starting with.x,&&,||,?,:).
Top-level declarations
struct Todo { id: Int, title: String, done: Bool = false } // fields `name: Type [= default]`
enum Filter { all, active, done } // values: .all .active .done
const maxItems = 50
fn total(xs: [Int]) -> Int { return xs.sum() } // no `-> T` = returns nothing
extern fn share(text: String) -> Bool // a platform call
extern fn load(id: Int, done: fn(Item?, String?)) // an async call: callback
extern event orderUpdated(order: Order) // a platform event
theme { brand: #7C3AED, primary: #7C3AED, font: "Inter" } // color tokens and the default font
theme dark { brand: #C4B5FD } // dark-mode values
view Name(params) { members }
Declaration order does not matter: types and functions can refer to each other in any
order. Keywords from other languages (func, function, component, class,
interface…) are recognized and fixed to the Vard equivalent (E0110, with fix:).
Types
| Type | Example | Notes |
|---|---|---|
Int | 42 | 64-bit integer; Int / Int truncates |
Float | 3.5 | Int converts to Float implicitly; back with toInt() |
String | "Count: {n}" | interpolation {expr}; escapes \n \t \" \\ \{ \} |
Bool | true | |
Color | #RGB #RRGGBB #RRGGBBAA | or a token such as .primary |
[T] | [1, 2] | list |
[String: T] | ["a": 1], [:] | map; keys are always String (E0125) |
T? | nil | optional |
fn(A, B) -> R | x => x * 2 | function |
struct/enum | Todo(id: 1, title: "A"), .active | user-defined |
Nothing but Int → Float converts implicitly. Strings are built by interpolation:
"a" + n is an error fixed to "a{n}". + joins only String + String.
When a type cannot be inferred (an empty list, nil), annotate it:
state items: [Todo] = [], state picked: Todo? = nil (E0308).
Views
view Card(title: String, onTap: fn() = {}, bind value: Bool, content: slot) {
state count = 0 // reactive mutable state (the initializer runs once)
state items: [Todo] = []
pref darkMode = false // state kept by the platform; app-wide by name
let doubled = count * 2 // derived value, recomputes itself, read-only
fn inc() { count += 1 } // can read and write state
on appear { load() } // event handler while the view is on screen
on back if count > 0 { count -= 1 } // `if` = active only while the condition holds
Column(gap: 8) { // then exactly one UI tree
Text(title)
content // a bare lowercase name inserts the slot parameter
}
}
Order inside a view: members first (state, pref, let, fn, on), then elements.
A view body is declarative: there are no statements in the tree (E0113); logic lives in
fn members and handlers.
Parameters
| Form | Meaning |
|---|---|
name: Type [= default] | read-only; reactive — updates when the caller’s value changes |
bind name: Type | two-way: the caller passes a mutable place (Checkbox(value: todo.done)) |
name: slot | a child block: Card { Text("Hi") }; at most one slot per view |
The first argument (the first non-slot parameter) may be positional; the rest are always
name: value (E0207). Every view use also accepts “outer” props applied to its root:
width height minWidth minHeight maxWidth maxHeight aspectRatio grow alignSelf id opacity offsetX offsetY scale.
State: state, pref, let
state— a signal. Changing it re-runs exactly the props that read it.pref— the same as state, but the value is kept in platform preferences (SharedPreferences,UserDefaults, headless — the simulator’s memory) under the keyvard.pref.<name>and restored at launch. Any data type (structs, lists, maps). Allprefs with one name are one app-wide value, and their types must match (E0223).let— a computed value (lazy, cached, dependencies tracked automatically).
The UI tree
Element(args) { children } // braces only for elements that take children
if cond { ... } else if c2 { ... } else { ... }
for t in todos by t.id { ... } // `by` = a stable unique key
for t, i in todos by t.id { ... } // i = index (Int)
for i in range(0, 5) { ... }
by is effectively required for structs with an id (W0401 without it): the key keeps a
row’s identity across sorting and filtering. Two equal keys are R0002.
Elements are not values: they cannot be stored in a variable or returned from a function
(E0212); compose with views and slot parameters.
Expressions
+ - * / % == != < <= > >= && || ! cond ? a : b a ?? fallback x! (unwrap)
list[i] map["k"] (T?) s.field .name (an enum variant or a color token)
x => x.done (a, b) => a + b x => { stmts } { stmts } // lambdas
.name is resolved from the expected type: an argument, a variable’s annotation, or the
other side of == (x == .all). Lambda parameter types come from where the lambda is
passed — no annotations needed.
Not in Vard: self/this, ?. (E0121), ++/-- (E0115), ===, semicolons,
imports, classes, modifier chains (E0119), @State (E0124), { x -> } (E0126).
Each of these habits is recognized and comes with a fix.
Statements (function and handler bodies)
let x = 1 var y = 2 x = v x += v x -= v
map["k"] = v map["k"] = nil // removes the key
if c { } else { } for x in list { } return v print(a, b)
Built-in functions: range(a, b) (a to b-1), min, max, print (to the log:
vard run --do log).
What is mutable
state, pref, bind parameters, local vars, fields and elements of those
(todos[i].done = true, profile.name = "x", counts["a"] = 1) and the loop variable of a
for that runs directly over state (for t in todos by t.id { Checkbox(value: t.done) }).
Parameters, let and items of a computed list (for t in todos.filter(...)) are
read-only (E0401); such state is changed by key: todos.removeWhere(x => x.id == t.id).
Values are copied, never shared (copy-on-write inside the runtime): a function that receives a struct received a copy. The model never has to think about aliasing.
Methods and properties
| Type | Properties | Methods |
|---|---|---|
String | count isEmpty | trim() upper() lower() contains(s) startsWith(s) endsWith(s) split(sep) toInt() toFloat() |
Int | toFloat() toString() abs() | |
Float | toInt() round() floor() ceil() abs() fixed(digits) | |
[T] | count isEmpty first last | contains indexOf map filter find any all sum join sortedBy reversed; in place: append insert removeAt remove removeWhere clear |
[String: T] | count isEmpty keys values | contains(key); in place: remove(key) clear() |
Properties are read without (), methods are called with () (E0215 with a fix).
Themes and tokens
Colors in views are set through tokens only — then dark mode just works:
.background .surface .text .muted .primary .onPrimary .border .danger .success .warning .clear.
Custom tokens are declared in theme { } (light values) and theme dark { }.
font: "Inter" in a theme sets the default family (font files go into the project’s fonts/).
Details: UI.
Localized text
strings { hello: "Hello, {name}", items: "{n} items" } // the default table: the source language
strings ru { hello: "Привет, {name}", items: "{n} шт." } // a translation
view Greeting(name: String, n: Int) {
Column {
Text(t("hello", ["name": name]))
Text(t("items", ["n": "{n}"]))
}
}
t(key, [placeholder: value])returns the text for the currentlocale(a reactive global, e.g."ru","pt-BR"): the exact language table, else its base language (pt-BR→pt), else the default table. Changing the locale re-renders exactly the texts that uset().- The compiler checks literal keys against the default table (
E0240, with a fix for typos), placeholders against the default text (E0241), and reports missing translations (W0405). Placeholders are names ({n}), not expressions (E0242) — compute values in code. - The host sets the locale from the system (Android: the configuration’s first locale, also on
change); in tests: the
locale ruaction.
The platform boundary
extern fn is a call into the platform, extern event is an event from the platform with a
handler on name(params) [if cond] { }. Only data crosses the boundary (Int Float String Bool Color, structs, enums, lists, maps, optionals) and callbacks fn(T) for results that arrive
later (E0317). Details: Platform.
Qualified names
A name from a package can be qualified with the package name: charts.BarChart(...),
state s: ui.Style, geo.distance(a, b), and a std one with std.Button. This is needed
only when two packages conflict (E0231); otherwise names are written as they are. Names
starting with _ are private to their package.
UI: elements, layout, style
The unit is dp. Every element with its prop types: vard doc Column, vard doc Text; common
props: vard doc common. All of it is generated from one registry
(crates/vard-lang/src/registry.rs), so the docs cannot drift from the compiler.
Built-in elements
| Element | Props | Meaning |
|---|---|---|
Column / Row | gap align justify (+ wrap on Row) | flex containers; Row(wrap: true) flows children onto new lines |
Grid | columns gap align | equal columns, filled row by row |
Stack | align justify | children overlap; z-order = source order; a grow child fills the height |
Scroll | gap align | a vertically scrolling column; needs a bounded height (grow: 1) |
Text(text) | style size weight color textAlign maxLines strike underline italic font letterSpacing lineHeight | text |
Input | value (bind String) placeholder onSubmit onChange secure keyboard size weight font color placeholderColor | text field; on devices a native editor over the frame |
Image(src) | fit tint | a project file ("assets/logo.png") or an https URL |
Spacer | flexible empty space (grow: 1 by default) |
Std views (written in Vard itself, source: vard doc std):
Button(label, onTap, kind: .filled|.tonal|.outline|.text, enabled),
Checkbox(bind value, label), Switch(bind value, label), Card { }, Divider().
A design system is plain views: copy std’s pattern (tokens + a kind parameter).
Layout
The model is CSS flex semantics in a single pass: constraints go down, sizes go up.
align— the cross axis:.start .center .end .stretch(default.stretch).justify— the main axis:.start(default).center .end .between .around .evenly.grow— a share of the free space on the main axis;alignSelfoverridesalignfor a child.- Sizes:
width height minWidth minHeight maxWidth maxHeight aspectRatio. - Spacing:
padding paddingX paddingY paddingTop paddingBottom paddingLeft paddingRight;safeArea: .top|.bottom|.all|.vertical|.horizontaladds the system insets to padding.
Every node remembers why it got its size on each axis. vard run --do 'why @2' prints
the chain of rules up to the root — the main tool for “why doesn’t it fit”:
> why @2
Text @2 358x32 at 16,16 examples/todo/app.vard:27
width: stretched by parent Column (align: .stretch)
height: content (1 line(s) x 32dp)
in App @1 390x844 at 0,0 examples/todo/app.vard:26
width: stretched by parent Column (align: .stretch)
height: grow: 1 share of parent's free space
Common props
Every element accepts: sizes and grow, padding, background, gradient ([Color]) and
gradientAngle (CSS degrees, 180 = down), radius and per-corner radii
(radiusTopLeft…), border and per-side borders, borderColor, shadow
(.sm .md .lg .xl .xxl), shadowColor, opacity, offsetX/offsetY, scale, clip,
alignSelf, onTap, id, and semantics: role (.button .checkbox .switch .heading .link .image), label, checked, enabled.
id: "email" gives a stable address #email for tests and inspection. A non-unique id on
screen is lint L006.
Typography
style: .display 34, .title 24, .heading 18, .body 16 (default), .label 15 bold,
.caption 13. weight: .thin … .black (100–900). Project fonts go into fonts/
(Inter-SemiBold.ttf → family Inter, weight 600); select with font: "Inter" on an
element or in the theme. Headless layout uses the bundled DejaVu font, so it is identical on
every machine; on devices the platform shaper measures text, and line breaks match what the
layout computed.
Tokens and themes
theme { brand: #7C3AED, primary: #7C3AED, onPrimary: #FFFFFF }
theme dark { brand: #C4B5FD, primary: #A78BFA, onPrimary: #1E1B4B }
- Semantic tokens:
.background .surface .text .muted .primary .onPrimary .border .danger .success .warning .clear. Pairings:.text/.mutedon.background/.surface,.onPrimaryon.primary. Contrast below WCAG AA is lintL005. - Custom tokens are declared in a theme and used as
.brand. - Raw hex colors in views break dark mode — use tokens.
- Dark theme: the system’s, or
setColorScheme(.dark|.light|.system); read it with the globalisDark; in tests —theme darkor@dark.
“Make it like Tailwind / Material / iOS”: vard doc design has class → prop mapping tables;
the tailwind package (vard add tailwind) ships the full palette, semantic tokens with
dark values and the components TwButton TwCard Badge Avatar Field.
UI lints
After a script, vard run prints lints — real bugs, not style:
| Code | What |
|---|---|
L001 | children overflow their container (needs a Scroll, or grow: 1 on the flexible child) |
L002 | an interactive element smaller than 44×44 dp |
L004 | a container with children has zero width or height |
L005 | text contrast below WCAG AA |
L006 | a repeated id on screen |
The fix recipe: vard explain L001.
Reactivity and execution model
The decision and its alternatives: ADR-0002. This page explains how it works and what rules follow for code.
The graph
| In code | In the runtime |
|---|---|
state x, pref x | Signal — a cell with a list of subscribers |
let y = ..., view parameters | Computed — a lazy cached value; dependencies are collected on read |
| every dynamic prop | Effect — writes one field of one node |
if / for in the tree | a structural Effect over a fragment of the tree |
| a view | Scope — owns everything created inside it |
A view body runs once, at mount. After that, changing a state wakes exactly the
effects that read it: count += 1 rewrites the text of one Text and rebuilds nothing.
No virtual DOM, no component re-rendering, no manual memoization.
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, enum values, lambdas) create no effects at all.
Lists
for t in todos by t.id reconciles rows by key. Each row has its own value signal, so
changing one item of a 3000-item list re-runs the effects of one row (measured in the
repository: 7 actions over 3000 rows — 35 effect runs). Without by, rows are matched by
position: a reorder turns into changes in every row.
Order and consistency
Effects run in creation order (parent before child), so there are no intermediate
inconsistent states (“glitches”). Disposing a scope (a view left the screen, an if branch
switched) frees all of its effects, nodes, signals and event handlers.
Rules for code
- Rendering is pure. Writing state while computing a prop, a
letor anif/forcondition isR0003. Writes go into handlers (onTap,onChange,onSubmit,on event) and functions called from them. - A
letdoes not read itself (R0004), directly or through otherlets. - Values are copied.
let t = todos[0]; t.title = "x"does not change the list; change the place:todos[0].title = "x". - Keys are unique.
R0002— two equalbykeys.
Runtime errors do not crash the app: the problem becomes an R diagnostic with
file:line, the value becomes nil.
Measuring
vard run --do 'tap "Add"; stats' prints effect runs, layouts and node count — enough to see
wasted work without a profiler.
Platform and native modules
Everything platform-specific goes through two declarations — they are also the boundary between Vard and native code:
extern fn name(params) -> T— the app calls the platform;extern event name(params)— the platform tells the app; the handler in a view,on name(params) [if cond] { ... }, is active while the view is on screen.
The standard platform is declared in Vard itself (vard doc std); every function is
implemented by the headless simulator and by the Android host (iOS is on the roadmap). The
reference for agents is vard doc native.
Lifecycle and system
on appear { load() } // this view instance was just shown
on appResume { refresh() } on appPause { save() }
on deepLink(url) { route(url) } // vard://...
Globals (reactive, read-only): safeArea (top bottom left right), keyboardHeight,
backProgress, isDark, screenWidth, screenHeight, platform.
Functions: setColorScheme(.dark|.light|.system), openUrl(url), shareText(text),
haptic(.success), openAppSettings().
Back and predictive back
on back if stack.count > 1 { stack.removeAt(stack.count - 1) }
Column(offsetX: backProgress * 64, opacity: 1 - backProgress * 0.3) { ... }
The innermost enabled handler takes the gesture. With none enabled, the system handles back (on Android 14+ with the system back-to-home animation). Whether the app intercepts back is passed to the host in every frame.
Edge-to-edge
The root always draws under the system bars. If the code never mentions safeArea, the
runtime pads the root itself. Otherwise you control placement: safeArea: .top on an
element adds the insets to its padding, safeArea.bottom reads the value (including the
keyboard). The focused input scrolls above the keyboard automatically.
Storage
pref onboarded = false // settings, app-wide by name
let t = secureGet("token") // String? — Keychain / Android Keystore (AES-256-GCM)
secureSet("token", value) // -> Bool; secureRemove("token")
prefGet(key) / prefSet(key, v) / prefRemove(key) // raw string preferences
Secrets go into secure* only, never into pref.
Permissions
state cam: PermissionStatus = .notDetermined
on appear { cam = permissionStatus(.camera) }
Button("Allow camera", onTap: { requestPermission(.camera, s => { cam = s }) })
if cam == .blocked { Button("Open settings", onTap: { openAppSettings() }) }
Permission: .notifications .camera .microphone .location .photos .contacts.
PermissionStatus: .notDetermined .granted .denied .blocked (blocked — the system will
not show the dialog again). On Android the permission must be in the manifest; a missing one
answers denied and logs what to add.
Notifications and push
on pushReceived(m) { inbox.insert(0, m) } // arrived while the app is open
on pushOpened(m) { route(m.data["screen"] ?? "") } // the user tapped a notification (also cold start)
on pushTokenChanged(t) { sendTokenToServer(t) }
getPushToken(t => { token = t ?? "" })
showNotification("Title", "Body", ["screen": "inbox"])
The push provider on Android is FCM from the firebase package.
Your own native functions
- Declare the API in Vard; data are structs and enums:
struct Place { name: String, lat: Float, lng: Float } extern fn searchPlaces(query: String, done: fn([Place], String?)) extern event locationChanged(lat: Float, lng: Float) - Build the UI and test it headless (
mock,resolve,emit— see Testing). - Generate typed Kotlin:
vard bindings --kotlin --class PlacesModule --out ...and implement the abstract methods (callbacks may be answered from any thread;send()instead ofresolve()for listeners). - Register it:
MainActivity.modules(),dev.vard.module.<name>meta-data in a library’s manifest — or, better, ship it as a package with[native.android]: then any app gets it with onevard add, and the Android shell includes the module by itself (Writing a package).
How data crosses
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* from the firebase package returns a document,
and Vard turns it into your struct.
Functions in arguments become {"$callback": id}; the host answers with
callback(id, json, keep). A callback of a view that has left the screen is dropped
silently. A function not implemented on the device is R0010.
extern fn/extern event names are global to the app: the platform calls them by name.
Two packages cannot declare the same native name (E0233).
Testing and debugging
Rationale: ADR-0003 — a screen as text costs ~100 tokens versus 450–1600 for a screenshot and, unlike an image, carries exact sizes and their causes.
Headless runs
vard run [PATH] --do "ACTIONS" [--view NAME] [--size 390x844] [--dark]
vard run --script steps.txt
Every run mounts the app from scratch and replays the actions — deterministic, 50–100 ms, no emulator. A “session” is a list of actions: to continue, replay the whole list with the new step at the end.
The action language
One action per line or separated by ;. The full list: vard doc actions.
| Action | What it does |
|---|---|
tree | the semantic tree with @ids (the default) |
layout | every node with [x,y WxH], style and file:line |
tap SEL · type SEL "text" · submit SEL · focus SEL · scroll SEL DY | interaction |
why SEL | why the element has this size and position — up the parent chain |
find SEL · state · log · stats · lint | inspection |
expect SEL · expect "text" · expect no "text" | assertions |
expect SEL checked|unchecked|enabled|disabled|offscreen|visible | element state |
theme light|dark · size W H · insets T B [L R] · keyboard H · locale TAG | environment |
shot FILE.png [scale] | a screenshot (only to judge visual design) |
Selectors: @12 (id from tree), #email (the id: prop), "Sign in" (exact label, then
whole word, then substring). Mutating actions print a diff of the tree: + added,
- removed, ~ changed.
The platform simulator
The headless platform Sim reproduces everything in Platform:
permission notifications answer denied # what the dialog will answer (default granted)
permission camera granted # the current status
push received "Title" "Body" {"screen":"inbox"}
push opened "Title" "Body"
emit deepLink "vard://item/7" # any extern event, arguments as JSON
back back 0.5 back cancel
insets 47 34 keyboard 300 focus #email
restart # cold start; prefs/secure/permissions kept
storage # dump prefs, secure values, permissions, notifications
Your own extern fns:
mock NAME VALUE # the function returns VALUE, its callbacks receive VALUE
pending # which calls are waiting for a result
resolve NAME VALUE # complete the oldest pending call (loading states!)
send NAME VALUE # deliver a value to a listener and keep it pending
A callback with two parameters receives a JSON array:
resolve firestoreListNotes [[{"title":"A"}], null]. Packages set default answers in the
[sim] section of their manifest (for example, authCurrentUser answers nil); mock in a
test overrides them.
.vtest files
@view LoginScreen # optional headers
@size 390x844
@dark
@app ../other-project
type #email "a@b.c"
tap "Sign in"
expect "Welcome"
vard test [PATH] finds every *.vtest. A test runs against the nearest directory with a
vard.toml (that is how tests in a package’s example/ exercise the example), otherwise
against the given project. On failure only the failing step is printed (plus the screen at
that moment):
PASS tests/smoke.vtest (52ms)
FAIL tests/x.vtest
> expect "Welcome"
FAIL: "Welcome" not found
screen 390x844 light
App @1
Text "Hello, Vard" @2
...
1 passed, 1 failed
On a real device
A debug build of the Android shell listens for the same action protocol on
127.0.0.1:8472 (scripts run on the UI thread):
adb forward tcp:8472 tcp:8472
vard run --device 127.0.0.1:8472 --do 'tree; tap "Sign in"; expect "Welcome"'
Output, diffs and failures look exactly like headless runs, so the same .vtest steps and the
same habits work against the real screen (real fonts, real platform services). Any host can
offer it through the C ABI: vard_inspect_listen(app, "127.0.0.1:8472") once, then
vard_inspect_poll(app) on the UI thread (redraw when it returns 1).
Debugging order
vard check→ errors with fixes (--fixapplies them to a fixed point).vard run --do tree→ the screen as text.- Actions print only the changes.
why/layoutgive the numbers and the rule that produced a size.lint:lines and! Rxxxxare real bugs — fix them first.- A screenshot — only to judge how it looks.
Tooling: CLI and MCP
vard is the only tool a person or an agent needs. Output discipline: every command prints
the minimum needed to decide the next step. Success is one line; a failure is file:line,
the line of code and a fix. Exit code: 0 on success, 1 otherwise. PATH is a .vard file or
a project directory (default: the current directory).
Development
| Command | What it does |
|---|---|
vard check [PATH] [--fix] [--json] | types; --fix applies machine fixes to a fixed point (never touches package files); --json — diagnostics as an array |
vard run [PATH] [--do "…"] [--script FILE] [--view V] [--size WxH] [--dark] [--no-lint] | headless run and an action script |
vard run --device HOST:PORT [--do "…"] | the same actions against a running debug app (see Testing) |
vard test [PATH] | every *.vtest |
vard doc [TOPIC] | reference: no topic — the full one (+ the project’s packages); topics elements common actions std errors design native packages, an element/enum/view/package name |
vard explain CODE | explains an E/W/R/L/P code |
vard new NAME | a project with vard.toml, a test, AGENTS.md, skills and .mcp.json |
vard bindings [PATH] --kotlin|--swift [--package P] [--class C] [--out FILE] | typed Kotlin base class or Swift protocol (Codable types, call(name, json) dispatcher, emit… helpers) for the project’s extern fn/event (excluding packages’ externs — they ship their own implementation) |
Packages
| Command | What it does |
|---|---|
vard search WORDS | search by name, keywords, summary and exported names in all of the project’s registries |
vard info NAME [PATH] | versions, capabilities with explanations, dependencies, publication time and provenance, the full API, tests at publish time |
vard add NAME[@REQ] [PATH] [--path DIR | --git URL [--tag T|--rev R|--branch B] [--dir D]] [--registry R] [--allow CAPS] [--allow-new] | add a dependency (exact names only), install, update vard.lock; --allow records the approval in [policy]; --allow-new confirms a quarantined package |
vard remove NAME [PATH] | remove a dependency |
vard install [PATH] [--allow CAPS] [--allow-new] | resolve vard.toml, download and verify, rewrite vard.lock |
vard update [NAME] [PATH] [--major] | raise requirements to the newest versions (git: re-resolve the branch/tag); prints the API diff |
vard api [PATH|NAME] [--caps] | public API and capabilities (with evidence: which call needs which capability) |
vard pack [PATH] [--out FILE] | a deterministic .vpk archive |
vard publish [PATH] --registry DIR|URL|NAME [--token T] [--dry-run] | the gate and publishing |
vard yank NAME@VER --registry DIR [--undo] | withdraw a version |
vard bundle [PATH] --out DIR|FILE.vpk | everything a device needs + bundle.json |
vard ota init DIR / vard ota publish [PATH] --channel DIR [--version V] | signed over-the-air update channels keyed by the native fingerprint (Delivery) |
vard registry init DIR [--name N] | create a registry (public/ + private/) |
vard registry token DIR OWNER | a publish token (shown once) |
vard registry serve DIR [--addr HOST:PORT] | HTTP hosting of a registry (web page at /) with a publish API |
vard registry rotate-key DIR | hand the registry over to a new signing key (signed by the old one) |
vard registry verify DIR|URL | verify signatures, the log chain and every archive |
Environment variables: VARD_HOME (cache, keys, tokens; default ~/.vard),
VARD_REGISTRY (the default registry for every project), VARD_OFFLINE=1 (never contact
the public registry; builtin becomes the default), VARD_TOKEN (publish token).
vard publish --owner LOGIN sets the owner when trusted CI writes a directory registry
(the public registry’s workflow passes the pull request author).
The MCP server
vard mcp speaks JSON-RPC 2.0 over stdio and works on the files of the project it is
pointed at, so it runs on the developer’s machine — there is nothing to host. vard new puts
.mcp.json into the project:
{ "mcpServers": { "vard": { "command": "vard", "args": ["mcp"] } } }
Other ways to get it:
- MCP Registry:
io.github.vardemin/vardui(registry.modelcontextprotocol.io), published by the release workflow; clients that read the registry can install it directly. vard.mcpbon every release — a one-file bundle (macOS universal, Linux x86_64, Windows x86_64) for clients that install MCP bundles, such as Claude Desktop.- Claude Code without a project file:
claude mcp add vard -- vard mcp.
| Tool | Equivalent |
|---|---|
vard_check | vard check (fix: true) |
vard_run | vard run --do |
vard_screenshot | a PNG after actions (expensive in tokens — only to judge design) |
vard_test | vard test |
vard_doc | vard doc (including package docs) |
vard_explain | vard explain |
vard_search, vard_info | search and a package card |
vard_add | vard add without --allow: approving a sensitive capability is a person’s decision |
vard_update | vard update with the API diff |
vard_api | vard api |
vard_publish_check | the publish gate without publishing |
vard_bindings | vard bindings --kotlin |
The tools are stateless: vard_run mounts the app from scratch on every call (50–100 ms), so
nothing can go stale between calls. Publishing through MCP is deliberately absent — it is an
outward-facing action a person takes.
Diagnostics
Every diagnostic carries a stable code, the location and the line of code, and — when the
fix is known — a fix: that vard check --fix applies. A short explanation:
vard explain CODE; the full list with explanations: vard doc errors.
app.vard:2:14 error E0202: unknown prop `fontSize` on `Text`
2 | Text("Hi", fontSize: 18)
fix: `fontSize` -> `size` (auto: vard check --fix)
Classes
| Prefix | Where | Examples |
|---|---|---|
E01xx | syntax | E0106 stray ;, E0110 a foreign keyword, E0111 an import, E0119 a modifier chain |
E02xx | names, elements, props, packages | E0201 unknown element, E0202 unknown prop, E0203 unknown name, E0206 missing required argument |
E03xx | types | E0301 type mismatch, E0304 unknown enum variant, E0314 optional not unwrapped, E0317 cannot cross the native boundary |
E04xx | mutability | E0401 assignment to something immutable, E0402 in-place method on an immutable list |
W04xx | warnings | W0401 loop without by, W0403 Input without value |
Rxxxx | runtime (printed as ! R0003 … (file:line)) | R0003 state written during render, R0010 no native implementation |
Lxxx | UI lints | L001 overflow, L002 small tap target, L005 contrast |
Pxxx | packages and registries (location: a line of vard.toml) | P001 no such package, P008 policy, P015 semver |
Packages in the compiler (E023x)
| Code | Meaning | What to do |
|---|---|---|
E0230 | a _ name is private to its package | use the public API (vard doc PACKAGE) |
E0231 | two direct dependencies export the name | qualify it: charts.Badge(...) |
E0232 | the name comes from a package that is not a direct dependency | vard add NAME |
E0233 | two sides declare the same native name | remove the duplicate or rename it on both sides |
E0234 | a name/parameter was renamed in a newer package version | vard check --fix |
E0235 | pkg.Name: no such package or no such public name | check the name; a typo comes with a fix: |
Package manager (P0xx)
| Code | Meaning |
|---|---|
P001 | no package with this name; “did you mean” lists real names |
P002 | the registry is unreachable or is not a Vard registry |
P003 | no version satisfies the requirement |
P004 | integrity failure: the archive hash differs, or the version is not in the signed log |
P005 | the registry key changed or the log history was rewritten |
P006 | incompatible requirements for one package (different major lines) |
P007 | the package needs a different vard core version |
P008 | a sensitive capability is not approved in [policy] |
P009 | the version was yanked |
P010 | an invalid, reserved or too-similar-to-someone-else’s name |
P011 | no AGENT.md, or it exceeds the 6 KB budget |
P012 | the package does not compile |
P013 | declared capabilities differ from the computed ones |
P014 | the package’s tests failed |
P015 | the version number does not match the API change |
P016 | the version is already published or is not newer than the latest on its line |
P017 | [sim] refers to an undeclared extern |
P018 | no token, or not the owner’s token |
P019 | the archive is larger than 8 MB |
P020 | vard.toml is not valid TOML (the subset Vard uses) |
P021 | a wrong or unknown field in vard.toml |
P022 | the project’s packages are missing or out of date |
P023 | a minor/patch release fails the previous version’s tests (behavior changed) |
P024 | the package is new (first published < 72 h ago): a person confirms with --allow-new |
P025 | a git dependency could not be fetched, or its tag/rev/branch does not exist |
Rules for new diagnostics (for framework developers)
A new code is stable, has an entry in explain.rs (compiler), vard_runtime::EXPLAIN
(runtime, lints) or vard_pkg::EXPLAIN (packages), and a fix whenever the correct edit is
known. When the fix is obvious, checking continues as if it were already applied — one
iteration instead of several, no avalanche of follow-up errors.
Package system overview
The problem
In today’s ecosystems (npm, Cargo, Go modules, SwiftPM, pub.dev) a package is an archive of code plus what its author claims about it: a version, a description, dependencies. Everything else — what the package can do, what breaks on upgrade, whether to trust it — a person finds out by reading code, changelogs and issues.
In VardUI, dependencies are mostly added by an LLM agent. For an agent the usual model has three systemic defects:
- Hallucinated names. Models confidently “remember” packages that do not exist, and attackers register those names (“slopsquatting”). Installing by a guessed name is a classic attack path.
- Claims instead of facts. Semver is an honor system; changelogs are written for people; what a package does with the device is written down nowhere. An agent cannot check any of it more cheaply than by reading all of the code.
- Expensive knowledge. To start using a package an agent reads a README of thousands of tokens, and after an upgrade it guesses what was renamed.
The solution: package = code + contract + knowledge + proof
| Part | What it is | Who produces it |
|---|---|---|
| Code | .vard sources, optionally a native module and resources | the author |
| Contract | the public API and capabilities | the compiler — computed from code, not declared |
| Knowledge | AGENT.md ≤ 6 KB (≈ 1500 tokens) + the generated API + skills | the author + the compiler |
| Proof | headless tests of example/ and the package, run by the registry at publish | the registry |
| Migrations | renames that become fix:es for consumers | the author |
| Simulation | [sim] answers for the package’s externs in headless mode | the author |
This gives properties classic package managers do not have:
- Semver is enforced. The compiler compares the new version’s API with the previous
one: removing or changing something is major, adding is minor, anything else is a patch.
The registry will not accept 1.0.1 with a broken API (
P015) and suggests the minimal acceptable version. - Capabilities are facts, not promises. The compiler sees the code call
secureGet, declare anextern fn, subscribe topushReceivedor loadhttps://. The manifest must match what was computed (P013); the consumer must approve sensitive capabilities in[policy](P008);vard.lockrecords them, so a new capability in a dependency is a line in a code-review diff. - Upgrades are mechanical.
vard updateprints the API diff, andvard check --fixapplies the package’s migrations to the app’s code (E0234). The agent does not read a changelog. - Installation never guesses.
vard addinstalls exact names only; a typo gets “did you mean” from the real index (P001). The registry refuses a name one edit away from an existing name of another owner (P010). - Knowledge is cheap and bounded.
vard docshows the project’s packages one line each;vard doc NAMEshowsAGENT.mdand the generated API. The document budget is checked at publish (P011). The package block in the project’sAGENTS.mdis updated on install, so an agent sees the dependencies without a single tool call. - A package is verifiable without a device. Tests run headless at publish;
[sim]gives consumers a workingvard runright aftervard add, even for packages with native code.
Namespaces without imports
The language deliberately has no imports (ADR-0001): one form of writing, no line where a model can get a path wrong. Packages keep that:
- an unqualified name is looked up in its own package (the app is a package too), then in direct dependencies, then in std;
- your own declarations always win over packages;
- if two direct dependencies export a name —
E0231, writepkg.Name; - transitive dependencies are invisible (
E0232),_names are private (E0230); extern fn/eventnames are global — the platform calls them (E0233).
The result: adding or upgrading one package cannot change the meaning of anyone else’s
code. The compiler renames conflicting declarations to pkg.Name before type checking, so
the runtime and inspection know nothing about packages. Details:
Using packages; implementation: crates/vard-lang/src/link.rs.
Version resolution: minimal version selection
A requirement is a minimum on a compatibility line ("1.4" = ≥ 1.4.0, < 2.0.0). For each
package the largest of the minimums anyone requires is selected
(ADR-0006). No SAT solver, no “latest”: the result
depends only on the manifests — today, tomorrow and in CI. The lockfile decides nothing; it
pins hashes and records capabilities. One version of a package per app (a shared
namespace); incompatible lines are P006.
Hosting: static, content-addressed, signed
A registry is a set of static files (ADR-0007):
config.json, catalog.json, index/NAME.json, blobs/SHA256.vpk, and a signed log
log.txt + log.head. Any CDN, bucket, GitHub Pages or directory can serve it;
vard registry serve adds a publish API. A client pins the registry key on first contact,
verifies the signature and the log’s hash chain, and then the hash of every archive. Trust
does not depend on the host: a mirror can delay an update but cannot substitute what was
published. Details: Registries and hosting; threats: Security model.
Delivery to devices
vard bundle collects everything a device executes: the app’s and packages’ sources
(@name/...), vard.lock, resources, and bundle.json with a hash and a native
fingerprint — the list of externs and native modules. The Android shell runs
vard bundle during the build and includes the packages’ native modules automatically. The
fingerprint is the compatibility key for over-the-air updates: an interpreted bundle can be
delivered without rebuilding the APK as long as the native part did not change. Details:
Delivery to devices.
What is implemented and what is on the roadmap
| Implemented (v0.3) | Roadmap |
|---|---|
| vard.toml, vard.lock, MVS; registry, path and git sources (commit + content hash pinned) | — |
namespace linker, pkg.Name, privacy; migrations of names, view params, enum variants and struct fields | migrations of field types (a type change is a major version today) |
| API and capabilities computed by the compiler; enforced semver; the previous version’s tests run against minor/patch releases | — |
| publish gate: compile, capabilities, tests, semver, behavior, AGENT.md budget, name; publication time and provenance | signed build attestations (Sigstore) |
quarantine of new remote packages (--allow-new) | — |
| static registry, signed log, key pinning, prefix check, signed key rotation | Merkle inclusion proofs instead of the full log (needed beyond ~100k versions) |
vard registry serve with token-based publishing, yank; a web page in every registry | organizations and roles |
the public registry vard on GitHub Pages, publishing by pull request; the builtin registry | — |
vard bundle with the native fingerprint; automatic native modules on Android | an OTA update client in the Android/iOS hosts; iOS modules in packages |
Using packages
Find and add
vard search bar chart # by name, keywords, summary and exports
vard info charts # before adding: versions, capabilities, API, tests
vard add charts # exact name; writes vard.toml and vard.lock
vard doc charts # AGENT.md + the API generated by the compiler
$ vard search chart
charts 1.0.0 [lan] — Bar charts drawn with Vard elements
caps: none · exports: Badge BarChart · tests 1 ✓
details: vard info NAME · install: vard add NAME
$ vard add charts
added charts 1.0.0 (lan)
caps: none
api: 2 views — `vard doc charts`
vard.lock: + charts 1.0.0
vard.lock: + tailwind 1.0.0
next: vard check
Variants:
vard add charts@1.4 # minimum version 1.4.0 on the 1.x line
vard add auth --registry acme # from a specific registry
vard add ui --path ../ui # a local package (monorepo)
vard add charts --git https://github.com/acme/charts --tag v1.4.0 # straight from git
vard add firebase --allow native # approving a sensitive capability
vard remove charts
A typo never turns into installing something similar:
$ vard add chart
error P001: no package `chart` in registry `acme`; did you mean: charts?
fix: search instead of guessing: vard search chart
An app’s vard.toml
[app]
name = "shop"
[dependencies]
charts = "1.4" # >= 1.4.0, < 2.0.0
legacy = "0.3" # 0.x: the 0.3.* line (as in Cargo)
exact = "=2.1.3" # exactly this version
auth = { version = "2", registry = "acme" } # from the acme registry
ui = { path = "../ui" } # a local package
widgets = { git = "https://github.com/acme/widgets", tag = "v2.1.0" }
mono = { git = "../monorepo", branch = "main", dir = "packages/mono" } # rev = "…" also works
[policy]
allow = ["native", "push"] # approved sensitive capabilities
[registries]
acme = "https://vard.acme.dev" # http(s) or a directory
default = "acme" # where dependencies without registry= come from
The manifest can be edited by hand: any vard command (check, run, test, doc) notices that
vard.lock is stale and reinstalls, saying so in one line.
Registries are looked up in order: the project’s [registries] → ~/.vard/config.toml →
the public registry vard (vardemin/vard-registry,
served at https://vardemin.github.io/vard-registry) → builtin (the packages bundled with
the toolchain, available offline). The default registry is vard unless default (or the
VARD_REGISTRY variable) says otherwise; VARD_OFFLINE=1 removes the public registry and
makes builtin the default. Each dependency comes from
exactly one registry — its own registry = ... or the default — never “wherever it was
found”: this rules out dependency confusion attacks.
Git dependencies
{ git = URL, tag | rev | branch = "...", dir = "sub/dir" } takes a package straight from a
repository — any URL git understands, or a local path relative to vard.toml. The commit
the reference resolves to is pinned in vard.lock together with the content hash of the
package files, so a branch does not move under the project until vard update NAME
re-resolves it:
$ vard update charts
~ charts 1.0.0 -> 1.1.0 (git 3f2a9c1e0b7d -> 8c41d0a2e9f3)
Git packages go through the same capability policy as registry packages. A package that
depends on a git (or path) package cannot be published to a registry (P021): registries
only reference registry versions.
New packages are quarantined
A package from a remote registry whose first version was published less than 72 hours ago
is not installed without --allow-new (P024). Fresh packages are where look-alikes and
typosquats live, so a person confirms them after a look at vard info NAME (owner,
publication time, provenance — which CI run built the archive). vard search and the
registry’s web page mark such packages NEW. The MCP tool vard_add has no
--allow-new: an agent asks the user. Directory registries (your own) are not quarantined.
vard.lock
# vard.lock — written by `vard install`. Commit it; review caps= changes like code.
lock 1
root deps=charts
pkg charts 1.0.0 src=reg:acme sha256=100e077d… api=350f1ca96bc8 caps= deps=tailwind
pkg tailwind 1.0.0 src=builtin sha256=6d7a5aa6… api=386f0117f3f1 caps= deps=
One line per package, sorted — a diff reads like a review:
- a new
caps=value — the package gained a capability; - a new
sha256=under the same version — content substitution (the manager marks it!); api=— a short hash of the public API: equal hash = equal API.
Commit the lockfile. It does not choose versions — MVS does, from vard.toml.
Namespaces
After vard add, the package’s public names are visible in the app’s code without imports:
view App {
state data: [Int] = [10, 40, 25]
BarChart(values: data, max: 50)
}
| Situation | What happens |
|---|---|
| a name is both in your code and in a package | yours wins; the package keeps using its own internally |
| two direct dependencies export a name | E0231 — write charts.Badge(...) or tailwind.Badge(...) |
| a name from a transitive dependency | E0232 — add it explicitly (vard add NAME) |
a _ name from someone else’s package | E0230 — private |
a pkg.Name that does not exist | E0235, with a fix for a typo |
| two dependencies declare one native name | E0233 |
You can qualify views (ui.Card { }), types (state s: ui.Style), functions and constructors
(geo.distance(a, b), ui.Style(size: 2)); std.Button is the std view.
Capabilities and policy
| Capability | Meaning | Sensitive |
|---|---|---|
prefs | reads/writes preferences (pref, prefGet) | |
links | opens URLs in other apps | |
share | the system share sheet | |
deeplinks | receives deep links | |
secure | Keychain / Keystore | ✓ |
permissions | asks for runtime permissions | ✓ |
push | token, notifications, push events | ✓ |
network | loads remote resources (https:// in code) | ✓ |
native | declares extern fn/event: runs the package’s native code | ✓ |
Sensitive capabilities need approval in [policy] allow. Without it, installation is
refused:
error P008: not allowed by [policy]: firebase 1.0.0 needs native (declares extern fn/event: runs native code shipped with the package)
fix: a person approves this: add to vard.toml `[policy] allow = ["native"]` or rerun with --allow native
--allow records the approval in [policy] — it lands in the diff and goes through review.
The vard_add MCP tool does not accept --allow: the agent tells the user what the package
needs, and a person decides.
Upgrading
vard update # every dependency — to the newest compatible versions
vard update charts --major # across a major boundary
vard check --fix # the packages' migrations are applied to your code
vard test
$ vard update charts --major
~ charts 1.0.0 -> 2.0.0
API change: major
! ~ view BarChart: `max` removed, `scale` added
vard.lock: ~ charts 1.0.0 -> 2.0.0
next: vard check --fix (applies the packages' migrations), then vard test
$ vard check
app/app.vard:3:32 error E0234: `max` of `BarChart` was renamed to `scale` in charts 2.0.0
3 | BarChart(values: [10, 50], max: 80)
fix: `max` -> `scale` (auto: vard check --fix)
vard update changes the requirements in vard.toml (visible in the diff), then reinstalls.
Packages in headless mode
A package’s externs answer with values from its [sim] (for example, authCurrentUser →
nil); the rest stay pending until a test says resolve/send. mock in a test overrides
[sim]. That is why vard run works right after vard add — even for a package wrapping a
native SDK.
Diagnostics in package code
Package files are shown as @name/file.vard:LINE. Packages’ warnings are not printed (that
is the author’s business); errors are. vard check --fix never writes into package files:
they are inputs from the cache (~/.vard/cache/pkgs/).
Writing a package
Layout
charts/
vard.toml manifest: [package], dependencies, [sim], [[migrate]], [native.android]
bars.vard sources: every .vard outside the directories below
AGENT.md for agents (required, ≤ 6 KB)
README.md for people (optional)
example/ the proof app: compiled and tested at publish
vard.toml [dependencies] charts = { path = ".." }
app.vard
tests/*.vtest
skills/NAME/SKILL.md optional skills; consumers get them as .claude/skills/charts-NAME/
native/android/ an optional Gradle library with the native implementation
assets/, fonts/ resources
A package’s sources are all .vard files except those in example/ examples/ native/ skills/ tests/ and hidden directories. The archive gets every file except hidden ones,
target/, build/, *.vpk and vard.lock.
Examples in the repository:
packages/tailwind
(a design system) and
packages/firebase
(a native SDK).
The manifest
[package]
name = "charts" # [a-z][a-z0-9_]*, up to 32 chars; also the qualifier in code
version = "1.4.0"
summary = "Bar and line charts drawn with Vard elements" # one line — shown in search
keywords = ["chart", "graph", "bar"]
license = "MIT"
repository = "https://example.com/charts"
vard = ">=0.1" # core versions the package works with
capabilities = [] # must equal the computed set (`vard api --caps`)
[dependencies]
tailwind = "1.0" # registry versions only: path dependencies are not publishable
[sim] # headless answers for your extern fns (JSON in a string)
chartsServerTime = '1700000000'
[[migrate]] # renames → E0234 + fix for consumers
since = "2.0.0"
from = "BarChart.max" # a view parameter: View.param
to = "BarChart.scale"
[[migrate]]
since = "2.0.0"
from = "Chart" # a top-level name
to = "BarChart"
[[migrate]]
since = "2.0.0"
from = "Style.outline" # an enum variant (.outline -> .ghost) or a struct field
to = "Style.ghost"
[native.android]
module = "dev.example.charts.ChartsModule" # the VardModule class
gradle = "native/android" # an Android library inside the package
Public API
Public is everything declared at the top level that does not start with _: views,
structs, enums, functions, extern fn/event, constants, theme tokens. See what consumers
see:
vard api charts/ # API + capabilities with evidence
view BarChart(values: [Int], max: Int = 100)
view Badge(label: String)
capabilities: none
Recommendations:
- Helpers start with
_:view _Bar(...),fn _scale(...). They can change without a major version. - Exported names should be distinctive: they live in the app’s namespace. A conflict with
another package will not silently break the build (
E0231), but it forces consumers to qualify. - Parameters with defaults — adding one stays a minor change.
- A package’s theme tokens (
theme { }) become the app’s tokens: that is how design systems are shipped (this is howtailwindworks).
AGENT.md
What an agent reads to use the package (vard doc charts = AGENT.md + the generated API +
capabilities). The budget is 6 KB ≈ 1500 tokens (P011). Write for a model:
- one sentence — what it is and when to use it;
- the main views/functions — one compiling example each;
- non-obvious rules (what goes into a
bind, which tokens to use); - how to test headless: what
[sim]answers, what needsresolve/emit.
Do not repeat the API list — it is generated and always accurate.
The example as proof
example/ is an ordinary app that depends on the package by path. The publish gate
compiles it and runs every .vtest (a test runs against the nearest vard.toml). It is both
“how to use it” documentation and a check that the package works with the current core.
vard test charts/ # the package's and example/'s tests
Capabilities
The compiler computes capabilities from the code: calls to secureGet/secureSet →
secure, requestPermission → permissions, getPushToken, showNotification,
on pushReceived → push, pref and prefGet → prefs, openUrl → links, shareText →
share, on deepLink → deeplinks, https:// strings → network, declaring
extern fn/event → native. The manifest’s capabilities must match (P013, with a ready
replacement line). Extra capabilities are a warning: consumers would have to approve
something unneeded.
Native code
A package can ship the implementation of its extern fn/event:
- declare the API in Vard in the package’s sources;
- generate a base class:
vard bindings charts/ --kotlin --package dev.example.charts --class ChartsModuleBase; - put an Android library into
native/android/(build.gradle.kts, anAndroidManifest.xmlwith<meta-data android:name="dev.vard.module.charts" android:value="dev.example.charts.ChartsModule"/>, the Kotlin implementation); - add
[native.android]to the manifest; - set
[sim]so consumers can run the app headless.
The Android shell includes the module automatically: settings.gradle.kts asks
vard android-modules <app> and includes each library as :vard-<name>. Example:
packages/firebase/native/android.
Versions and migrations
The gate compares the API with the previous published version:
| Change | Minimal step |
|---|---|
| a name, parameter, field or enum variant removed | major |
a type, bind, return value or the first (positional) parameter changed | major |
| a parameter became required; a required parameter or a field without a default added | major |
| a name, enum variant, or a parameter/field with a default added | minor |
| nothing in the API | patch |
For 0.x a major change is a minor bump (0.3 → 0.4), as in Cargo.
error P015: API change since 1.0.0 is major: ! ~ view BarChart: `max` removed — the version must be at least 2.0.0
fix: version = "2.0.0"
Accompany every rename with [[migrate]] — then vard check --fix rewrites the consumer’s
code by itself. from = "X.y" means, depending on what X is in your package: a view’s
parameter, an enum’s variant (.y in consumer code), or a struct’s field (both
X(y: ...) and value.y).
Behavior is checked too
For a minor or patch release the gate also runs the previous version’s example/ tests
against the new code. They are what consumers relied on; if they fail, the release changes
behavior even when the API diff is clean (P023):
error P023: behavior changed: the tests of 1.0.0 fail against 1.0.1:
FAIL example/tests/total.vtest
> expect "Total: 60"
fix: restore the old behavior, or publish it as 2.0.0
On a new major line the old tests only produce a warning.
Publishing
vard publish charts --registry acme --dry-run # the gate only
vard publish charts --registry acme --token $TOKEN
gate: charts 1.0.0
ok AGENT.md: 78 B of 6.0 KB
ok compiles (1 file(s), 1 dependency)
ok capabilities: none
ok tests: 1 passed (headless)
ok api: 2 views (first version)
ok archive: 6 files, 822 B, sha256 100e077ddd80943d
published charts 1.0.0 to acme (log #1)
The gate checks: the name (valid, not reserved, not one edit from someone else’s), a
one-line summary, no path or git dependencies, AGENT.md and its budget, archive size (≤ 8 MB),
compilation with dependencies, capabilities, [sim], migrations, tests, version
immutability, semver and the previous version’s tests. It records the publication time and
provenance (in GitHub Actions: repository, commit and run URL; otherwise local), which
vard info and the registry’s web page show. The registry server runs the same checks when accepting over HTTP.
To withdraw a version (a serious bug, a leaked secret): vard yank charts@1.0.1 --registry DIR.
Existing lockfiles keep working; new resolutions skip it.
Registries and hosting
A Vard registry is static files. Reading is plain GETs with no server logic; writing
(publishing) happens in one place and always passes the same gate. So a registry can live
anywhere — in a directory, in an S3/R2/GCS bucket behind a CDN, on GitHub Pages, on nginx —
and be served through untrusted mirrors.
The public registry
vardemin/vard-registry is the default
registry of vard (name vard, https://vardemin.github.io/vard-registry). It is this
same format, kept in a GitHub repository and served by GitHub Pages — free for open source,
no server to run:
- Publishing is a pull request. Copy the package to
submissions/<name>/and open a PR; thecheckworkflow runsvard publish --dry-runwith the PR author as the owner. After a merge, thepublishworkflow publishes as the PR author, removes the submission, commitspublic/and redeploys Pages. - The signing key lives only in the repository’s Actions secrets (and with the
maintainer); its public half is compiled into
vard, so even the first contact is verified — no trust-on-first-use window. - Ownership is the GitHub login of the first publisher; later versions must come from their pull requests.
The rest of this page describes the format and how to run a registry of your own.
Create a registry
vard registry init ./reg --name acme
vard registry token ./reg alice # a publish token, shown once
vard publish ./charts --registry ./reg --token vard_…
reg/
public/ ← this is the registry: serve it as static files
config.json {"vard_registry": 1, "name": "acme", "key": "<ed25519 public key>"}
catalog.json one row per package: name latest summary keywords caps exports tests
index/charts.json JSON lines: one per version (+ yank status lines)
blobs/<sha256>.vpk immutable archives
log.txt the publication log (hash chain)
log.head size, chain head, ed25519 signature
index.html the registry's web page: search, versions, capabilities, API, provenance
private/ ← never publish this
registry.key the signing key
tokens sha256(token) owner
Read protocol
| Request | Response | Caching |
|---|---|---|
GET config.json | name, protocol version, public key | short |
GET catalog.json | the catalog for search (search runs on the client — the server computes nothing) | short |
GET index/NAME.json | every version of a package; 404 — no such package | short |
GET blobs/SHA256.vpk | an archive | forever (immutable): the address is the content hash |
GET log.txt, GET log.head | the signed log | short |
An index line:
{"name":"charts","version":"1.0.0","sha256":"100e…","size":822,"vard":">=0.1.0",
"deps":[{"name":"tailwind","req":"1.0","registry":"builtin"}],
"caps":[],"android":null,"summary":"Bar charts drawn with Vard elements","keywords":["chart"],
"api":[{"kind":"view","name":"BarChart","params":[{"name":"values","ty":"[Int]","default":null,"bind":false}]}],
"doc_bytes":78,"tests":{"passed":1,"failed":0},"tested_with":"0.3.0","owner":"alice","yanked":false,
"published":"2026-11-19T08:30:00Z",
"provenance":{"builder":"github-actions","repository":"https://github.com/vardemin/vard-registry","commit":"…","run":"…/actions/runs/…"}}
api is the full public API computed by the compiler at publish: vard info, search by
exports and the API diff in vard update work from it without downloading archives. A
dependency’s registry is where it resolved for the author (builtin, a URL or a
directory), so the consumer gets it from the same place.
Yanking is an appended line {"name":"charts","version":"1.0.1","yanked":true}: the index is
append-only.
The log and its signature
log.txt 1 charts 1.0.0 <archive sha256> <chain_1>
2 charts 2.0.0 <archive sha256> <chain_2>
chain_n = sha256(chain_{n-1} " " n " " name " " version " " sha)
log.head 2 <chain_2> <ed25519("vard-log/1 2 <chain_2>")>
On first contact with a registry the client:
- pins its key (
~/.vard/known_registries, like SSH’sknown_hosts); a changed key isP005; - verifies the head’s signature and recomputes the chain;
- checks that the head it saw last time is a prefix of the new log (history was not
rewritten) —
P005; - installs only an archive whose
(name, version, sha256)is in the log and whose hash matches —P004.
vard registry verify DIR|URL verifies a whole registry: signatures, chain and every archive.
Rotating the key
vard registry rotate-key ./reg
The old key signs a rotation record {from, to, sig} that stays in config.json; the log
head is re-signed with the new key, and the old secret is kept as
private/registry.key.<id>.old. A client that trusts the old key (pinned, or compiled in for
the public registry) follows the chain of signed rotations to the current key and re-pins it
silently; a key that no signed rotation links to is still P005. After rotating, publish
public/ and update the CI secret with the new private/registry.key.
The web page
Every registry gets public/index.html (written by vard registry init, added by the next
publish to older registries): a single static page, no external scripts, that reads
catalog.json and index/NAME.json. It shows search over names, keywords, summaries and
exports; capabilities with sensitive ones highlighted; publish-time test results; versions
with publication time, yank status and provenance; the generated API; and the
vard add NAME command. vard registry serve serves it at /.
Hosting
A directory or a network share
[registries] acme = "/mnt/share/vard-registry" — the client reads the files directly. Good
for a team and for CI.
vard registry serve
vard registry serve ./reg --addr 0.0.0.0:8470
GET /…— static files frompublic/; archives withCache-Control: immutable.POST /api/v1/publish— body: a.vpk, headerAuthorization: Bearer TOKEN. The server unpacks the package into a scratch directory, runs the same gate asvard publish(compile, tests, semver, capabilities…) and appends to the log. The response is the gate report.POST /api/v1/yank— bodyNAME VERSION [undo], owner only.
The first publisher of a name becomes its owner; other tokens get P018. The server speaks
HTTP — put it behind any TLS terminator. Integrity does not depend on TLS.
A CDN or a bucket
Publish locally (vard publish --registry ./reg) or in CI, then sync public/:
aws s3 sync reg/public s3://vard-registry --cache-control "no-cache"
aws s3 cp reg/public/blobs s3://vard-registry/blobs --recursive --cache-control "public, max-age=31536000, immutable"
Clients: [registries] acme = "https://registry.acme.dev".
A registry in git (GitOps)
Keep public/ in a git repository. Publishing = a pull request that CI checks with
vard publish --dry-run and, after merge, applies with vard publish --registry using the
key from CI secrets; GitHub Pages serves the result. The registry’s history gets a second,
independent log — git.
Client configuration
| Where | What |
|---|---|
vard.toml [registries] | the project’s registries and default |
~/.vard/config.toml [registries] | the user’s registries (default = "acme") |
VARD_REGISTRY | the default registry for every project (CI) |
~/.vard/credentials.toml [tokens] acme = "vard_…" or VARD_TOKEN | publish tokens |
~/.vard/known_registries | pinned keys |
~/.vard/cache/ | archives (blobs/), unpacked packages (pkgs/), seen log heads |
The builtin registry is the packages from the framework repository’s packages/, compiled
into the binary. It works offline and needs no signature: its content is part of the
executable.
Private registries and mixing
A dependency comes from exactly one registry: its own registry = "..." or the default
registry. A name from a private registry cannot be “hijacked” by a public one, and vice
versa. For mirrors: a mirror needs no trust — it serves the same signed files.
Scaling
The current format targets thousands of packages: a client reads only the indexes of the packages it needs; the catalog is one file. For large registries (roadmap): a Merkle tree instead of the full log (O(log n) inclusion proofs, like Go’s sumdb), a sharded catalog, key rotation with the new key signed by the old one.
Delivery to devices
Vard code runs on a device in the runtime, from sources, so from Vard’s point of view “building the app” means a bundle: a deterministic set of files any host understands.
vard bundle
vard bundle examples/firebase --out build/app # a directory
vard bundle examples/firebase --out app.vpk # a single archive
build/app/
app.vard the app's sources
@firebase/firebase.vard package sources (the @name/... path marks a package file for the linker)
vard.lock the package graph — the compiler on the device reads it by itself
fonts/, assets/ project resources
bundle.json metadata
{
"vard": "0.1.0",
"sha256": "f626985f…",
"native_fingerprint": "cffccd18…",
"natives": ["android firebase dev.vard.firebase.FirebaseModule", "event authChanged", "fn analyticsLog", "…"],
"caps": ["native"],
"packages": [{ "name": "firebase", "version": "1.0.0", "sha256": null }]
}
sha256— the hash of the bundle content (the same deterministic.vpkformat).native_fingerprint— the hash of the sorted list of everything that must exist in the native part:extern fnandextern eventnames and the packages’ native modules.caps— the resulting capabilities of the app and its packages.
The device needs no package manager: the host passes the runtime a list of (path, text),
and vard_lang::compile recognizes @name/... files and vard.lock by itself. The FFI did
not change.
Android
The platforms/android build does everything itself:
settings.gradle.ktsrunsvard android-modules <vard.app>— the list of packages with[native.android]— and includes each library as:vard-<name>;:appdepends on them;- the
bundleVardApptask runsvard bundle <vard.app> --out build/generated/vardAssets/app; VardActivityreads*.vardandvard.lockfrom the assets; modules register throughdev.vard.module.*meta-data in the libraries’ manifests.
cd platforms/android
./gradlew installDebug -Pvard.app=examples/firebase
The -Pvard.firebase=true flag is gone: depending on the firebase package includes its
native module.
Over-the-air updates (OTA)
An interpreted bundle can be replaced without rebuilding and reinstalling the app — on one condition: the native part has not changed. That is exactly what the native fingerprint checks.
| Change | Fingerprint | Deliverable OTA |
|---|---|---|
| layout, logic, styles, texts | same | yes |
| a new version of a package without native code | same | yes |
a new extern fn / extern event or a new native module | different | no — needs a new app release |
vard ota init ./channel # once: prints the channel key to compile into the app
vard ota publish examples/todo --channel ./channel --version 1.0.1
channel/
public/config.json {"vard_ota": 1, "key": "<ed25519 public key>"}
public/bundles/<sha256>.vpk immutable bundles
public/<native_fingerprint>/latest.json {"sha256", "size", "version", "published", "sig"}
private/ota.key the signing key — never publish it
latest.json is signed over vard-ota/1 <fingerprint> <sha256> <version>. A device:
- downloads
<its own fingerprint>/latest.jsonand the bundle it names (static hosting, any CDN); - calls
vard_ota_install(latest, bundle, len, key, fingerprint, dir)(C ABI; Rustvard_ffi::ota_install) — it checks the signature with the key compiled into the app, the bundle hash, the fingerprint inside the bundle and that the sources compile, then writes the bundle todiratomically; any failure leaves the current bundle in place; - loads
dirinstead of the built-in bundle on the next start.
Implemented: channels, publishing, verification and installation (tested in
crates/vard-ffi/tests/ota.rs). Not yet: the download-and-swap loop inside the Android and iOS
shells (a few dozen lines of platform code around vard_ota_install).
The channel is addressed by the fingerprint, so a device physically cannot receive a bundle that needs native code it does not have. For AI-first development this closes the loop: an agent fixed a bug → the tests passed headless → a bundle with the same fingerprint safely goes to users; a change that needs new native code automatically becomes a store release.
Reproducibility
- The same
vard.tomlgives the same version selection (MVS);vard.lockpins the hashes. .vpkarchives are deterministic: sorted paths, no timestamps, no permissions.vard bundlegives the samesha256for the same inputs on any machine.- Offline: packages from the cache (
~/.vard/cache/),builtinand path dependencies need no network.
Package security model
The starting premise: dependencies are added by an agent that can make mistakes and can be deceived by text (documentation, an issue, a web page). So the system is built so that (1) the agent cannot install the wrong thing, (2) a package cannot get more than a person approved, and (3) nobody between the author and the device can substitute the code.
Threats and defenses
| Threat | Defense | Code |
|---|---|---|
| The agent “remembered” a non-existent name; an attacker registered it (slopsquatting) | vard add installs exact names only; a miss gets “did you mean” from the real catalog, never an automatic substitution; the MCP tool description requires searching, not guessing | P001 |
Typosquatting (tailwnd, charts ↔ chart) | the registry refuses a name one edit away from an existing name of another owner, and reserved words | P010 |
| A freshly registered malicious package | quarantine: a remote package whose first version is younger than 72 h needs --allow-new (not available through MCP); search and the web page mark it NEW | P024 |
| A package silently gains access to secrets, permissions, the network, native code | the compiler computes capabilities; the manifest must match; sensitive ones need [policy] allow; the MCP tool cannot approve | P013, P008 |
| An update gives a package a new capability | vard.lock stores caps=; the change is a ! line in the report and in the diff; without approval installation is refused | P008 |
| A private registry’s dependency replaced by a public one (dependency confusion) | a dependency comes from exactly one registry; where it resolved is recorded in the author’s index entry | — |
| An archive substituted on the host/mirror/CDN | content addressing: the archive is checked against the sha256 of the index and the lockfile | P004 |
| The index substituted | the (name, version, sha256) entry must be in the signed log | P004 |
| The whole registry substituted / MITM | the public registry’s key is compiled into vard; other registries’ keys are pinned on first contact; a changed key is an error | P005 |
| History rewritten (an old version quietly replaced) | the log is a hash chain; the client checks that the head it saw is a prefix; versions are immutable | P005, P016 |
| A package breaks other code by “capturing” names | your own names win; transitive dependencies are invisible; a conflict of two packages needs explicit qualification | E0231, E0232 |
| Two packages claim one native function | native names are global, a conflict is a compile error | E0233 |
| A false “backward compatible” | semver is computed from the API diff, and the previous version’s tests must pass against a minor/patch release | P015, P023 |
| A registry key must change (compromise, hygiene) | signed rotation records: clients follow the chain from the key they trust and re-pin; unsigned changes stay errors | P005 |
| Where did this archive come from? | every version records its publication time and provenance (CI repository, commit, run) | — |
| A malicious package with deliberately broken tests etc. | the gate runs on the server: compile, headless tests, size limit | P012, P014, P019 |
| Prompt injection through a package’s docs | AGENT.md is limited to 6 KB; the skill and the project’s AGENTS.md tell the agent never to approve capabilities by itself; approval happens only through vard.toml, which a person reviews | — |
| A leaked publish token | only sha256(token) is stored; a token is bound to its owner; yank to withdraw versions | P018 |
What the system does not promise
- No malicious intent in a package’s code. Capabilities limit what a package can do,
not how: a package with approved
networkcan send data. The approval is a person’s decision;vard infoshows why each capability is needed. - Native code. The
nativecapability means running the package’s Kotlin/Swift code outside Vard’s limits. Approve it as carefully as a Gradle dependency. - Availability. A mirror can withhold updates (a freeze attack). That is detectable only by comparing with another source; log witnesses are on the roadmap.
Recommendations
- Commit
vard.lockand watchcaps=andsha256=in diffs. - In CI:
vard install(without--allow) fails if someone added a dependency with an unapproved capability; runvard registry verify URLperiodically. - Keep a registry’s
private/out of public hosting; keep the key in CI secrets. - For agents: the
vard-packagesskill already contains the rule “onP008, stop and ask the user”.
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).
Android shell
The same Rust core (vard-runtime) as in vard run, built as libvard_ffi.so, plus a
Kotlin host that draws the result and connects the platform. Sources:
platforms/android.
platforms/android
├── vard/ library: libvard_ffi.so + VardView, VardHost, VardActivity, core modules
├── app/ the shell app: bundles a Vard project (vard.app) and extends VardActivity
(packages' native modules — `packages/*/native/android` — are included automatically)
assets/app/**.vard, fonts/, assets/ ──► VardNative.create ──► Rust: compile → mount → layout
│ frame(): draw records (format v2)
VardView.onDraw ◄──────────── ByteArray ───────────┘ rect, background, gradient, shadow, radii, text, ...
touch ─► VardNative.tap(x, y) hit-test and bubbling to onTap — in the core
EditText ─► inputText / submit / focus a real EditText over each Input, the IME works
extern fn ─► VardHost.call(name, json) ─► VardModule (Kotlin) ─► callback(id, json) / emit(event)
insets / back gesture / onResume / intents ─► setInsets / backProgress / back / emit(...)
What VardActivity does
| Feature | How it works |
|---|---|
| Edge-to-edge | the window draws under the status bar, navigation and cutout on every API 26+; bar, cutout and keyboard insets go to the core (safeArea); bar icons follow the app theme; the focused Input scrolls above the keyboard |
| Predictive back | android:enableOnBackInvokedCallback="true"; while the app has an enabled on back, an OnBackAnimationCallback (API 34+) is registered and the gesture progress goes to backProgress; otherwise the system shows its back-to-home animation. API 33 — OnBackInvokedCallback, below — onBackPressed |
| Permissions | PermissionsModule: requestPermissions + shouldShowRequestPermissionRationale → granted/denied/blocked; a permission missing from the manifest is denied with a hint in logcat |
| Preferences | PrefsModule over SharedPreferences; pref variables are stored there too |
| Keychain | SecureModule: AES-256-GCM, the key never leaves the Android Keystore |
| Notifications and push | VardPush: in the foreground — the pushReceived event, in the background — a system notification; a tap opens the app and sends pushOpened (also on cold start). The token and delivery come from a provider (the firebase package) |
| Lifecycle, deep links | appResume/appPause, deepLink(url) for vard://... |
| Modules | the core ones + every library with <meta-data android:name="dev.vard.module.<name>" android:value="<class>"/> + the app’s modules() |
| Fonts and images | the project’s fonts/*.ttf are registered in the core and drawn with the same file; Image("assets/x.png") from assets, https:// loaded in the background |
Requirements
| Component | Version | Where to get it |
|---|---|---|
| Rust | from rust-toolchain.toml | rustup target add aarch64-linux-android x86_64-linux-android |
| cargo-ndk | 4.x | cargo install cargo-ndk --locked |
| Android SDK | platform 35, build-tools 35 | Android Studio → SDK Manager |
| NDK | 28.2.13676358 (ndkVersion in vard/build.gradle.kts) | SDK Manager → SDK Tools → NDK (Side by side) |
| JDK | 17–21 | e.g. the JBR from Android Studio |
The Gradle wrapper (Gradle 9.3.1, AGP 9.1.0) is in the repository. The SDK path goes into
platforms/android/local.properties (not committed):
sdk.dir=C\:\\Users\\<you>\\AppData\\Local\\Android\\Sdk.
Build and run
From platforms/android:
./gradlew installDebug -Pvard.app=examples/native
adb shell am start -n dev.vard.host/dev.vard.app.MainActivity
| Property | Default | Meaning |
|---|---|---|
vard.app | examples/todo | which Vard project to package (path from the repository root) |
vard.abis | arm64-v8a,x86_64 | ABIs for cargo ndk -t; for an emulator -Pvard.abis=x86_64 is enough |
vard.skipCargo | false | do not call cargo, take prebuilt .so files from vard/src/main/jniLibs/<abi>/ |
vard.applicationId | dev.vard.host | the app’s applicationId |
Vard compile errors are shown on screen; runtime errors (R…) and module hints go to logcat:
adb logcat -s Vard VardFirebase
Driving the real screen from vard
Debuggable builds listen for the action protocol on 127.0.0.1:8472:
adb forward tcp:8472 tcp:8472
vard run --device 127.0.0.1:8472 --do 'tree; tap "Add"'
The locale follows the system language (Configuration.locales[0], also on change), so
t() texts switch with it.
Checking platform features on an emulator
A push through the same path as FCM (debug builds only, DebugPushReceiver):
adb shell am broadcast -a dev.vard.DEBUG_PUSH -p dev.vard.host --es title "Hi" --es body "Text" --es data '{"route":"inbox"}'
Predictive back on API 34 is enabled with a developer option (default on 35+):
adb shell settings put global enable_back_animation 1
A deep link:
adb shell am start -a android.intent.action.VIEW -d "vard://item/7" dev.vard.host
Your own native module (any SDK)
- Declare the API in
.vard:extern fn searchPlaces(query: String, done: fn([Place], String?)),extern event locationChanged(lat: Float, lng: Float). - Generate a typed base class:
vard bindings examples/myapp --kotlin --package com.example --class PlacesModule --out app/src/main/kotlin/PlacesModule.kt. - Implement the abstract methods (callbacks may be called from any thread) and return the
module from
MainActivity.modules()— or move it into a library with<meta-data android:name="dev.vard.module.places" .../>(that is how thefirebasepackage works), or better, ship it as a package with[native.android](see Writing a package): then the shell includes it by itself.
Firebase
vard add firebase examples/myapp --allow native
Put google-services.json into platforms/android/app/. No separate flag is needed: the
package declares [native.android] gradle = "native/android", and settings.gradle.kts
includes the module itself (vard android-modules examples/myapp shows what will be
included). Without the file the module starts, but every call answers
FirebaseError(code: "not-configured"). Firestore works with any app struct: declare
firestoreGet<X>/firestoreList<X>/… with your type — one native implementation serves
them all.
How the app gets into the APK
The bundleVardApp task runs vard bundle <vard.app> --out build/generated/vardAssets/app:
the app’s sources, the packages’ sources (@name/...), vard.lock (the package graph for
the linker), fonts/, assets/ and bundle.json with the content hash and the native
fingerprint (the list of externs and native modules). The fingerprint is the compatibility
key for delivering updates without rebuilding the APK
(Delivery to devices).
Limitations
- Drawing with
Canvas, a whole frame at a time; a GPU renderer and tree diffs are on the roadmap. - Shadows through
Paint.setShadowLayer(hardware-accelerated on API 28+). - Accessibility (TalkBack) is not yet connected to the semantic tree; scrolling has no inertia.
- There is no iOS shell yet: the C ABI for it (
vard_set_host,vard_callback,vard_emit,vard_back*,vard_set_insets) is ready.
Architecture decision records
| ADR | Decision |
|---|---|
| 0001 | Our own Vard language instead of a DSL in Kotlin/Swift/TS |
| 0002 | Fine-grained reactivity without a virtual DOM |
| 0003 | Text inspection as the primary debugging interface |
| 0004 | A knowledge base for agents, in English, compiled into the tool |
| 0005 | Packages with a contract computed by the compiler |
| 0006 | Minimal version selection instead of a solver |
| 0007 | A static, content-addressed registry with a signed log |
ADR-0001: Our own Vard language instead of a DSL in Kotlin/Swift/TS
Status: accepted
Context. Applications are written by an LLM. It needs a short reference, unambiguous rules, instant checking with fixes, and clear errors. Existing languages offer a huge surface (generics, inheritance, async models, 1–5 minute toolchain builds) and compiler errors designed for people.
Decision. A small statically typed language with syntax close to Swift/Kotlin/TS (strong priors in models), one way to write each thing, and a compiler that knows models’ typical “habits” from other frameworks and turns them into machine fixes.
Consequences. + the full reference ≈ 3k tokens; a check ≈ 20 ms; errors fix themselves.
− we maintain our own compiler and tooling; platform interop only through extern fn (see
the roadmap).
ADR-0002: Fine-grained reactivity without a virtual DOM
Status: accepted
Context. Performance is a key criterion. The “re-render a component and diff the trees” model (React, Compose recomposition, SwiftUI body) spends work proportional to the size of the subtree and requires memoization from the author — something models systematically get wrong.
Decision. Signals/computed/effects (like Solid/Leptos): a view body runs once, every
dynamic prop is a separate effect, structural if/for are effects over fragments, keyed
lists have a value signal per row, and equality cut-offs apply at every level.
Consequences. + the cost of an update is proportional to the change, not to the UI size;
the author needs no memo/key tricks (except by in lists, which the compiler checks).
− state cannot be changed while the UI is being computed (R0003) — a deliberate restriction
caught by the runtime.
ADR-0003: Text inspection as the primary debugging interface
Status: accepted
Context. A screenshot costs a model ~450–1600 tokens and requires “vision” to understand what is where. And exact sizes and the causes of a layout cannot be extracted from a picture.
Decision. A deterministic headless runtime and an action language (tree, tap,
type, why, state, lint, expect). Mutating actions print a diff of the semantic
tree. Tests (.vtest) and MCP use the same language. A bundled font makes layout identical
on every machine.
Consequences. + a screen ≈ 100 tokens, an action ≈ 30; reproducible bugs and tests without an emulator. − the headless render is not pixel-identical to the platform; the final visual check happens on a device (plan: the same protocol over a WebSocket to the device).
ADR-0004: A knowledge base for agents, in English, compiled into the tool
Status: accepted (amended: all documentation is in English)
Context. Documentation a model reads must be short, precise and must not drift from the compiler’s behavior.
Decision. knowledge/llms.txt is the complete reference; it is compiled into the binary
(vard doc, vard_doc in MCP), so the reference version always matches the compiler
version. Element descriptions (vard doc Text) are generated from registry.rs. Texts for
agents are in English (fewer tokens, stronger priors). The documentation for people —
README and the docs/ site (https://vardemin.github.io/vardui/) — is in English too, so one
language serves the whole community; it was originally written in Russian.
vard new puts AGENTS.md, CLAUDE.md, skills and .mcp.json into every project.
Consequences. + one source of truth; an agent gets everything it needs with one command.
− when the language changes, llms.txt and the skills must be updated; the snippets from
the vard-app skill live in examples/patterns and are checked by vard test.
ADR-0005: Packages with a contract computed by the compiler
Status: accepted
Context. Dependencies in VardUI projects are added mostly by an LLM agent. In classic package managers (npm, Cargo, pub, SwiftPM) a package is described by its author’s claims: version, description, changelog. For an agent that means: (1) a guessed name may belong to someone else’s package (slopsquatting), (2) semver and descriptions cannot be verified more cheaply than by reading the code, (3) what the package does with the device is written down nowhere, (4) an upgrade requires reading a changelog and editing by hand. Separately: the language deliberately has no imports (ADR-0001), and packages bring in foreign names.
Decision.
- A package = code + a contract computed by the compiler (public API and capabilities) +
knowledge (AGENT.md ≤ 6 KB, the generated API, skills) + proof (headless tests at publish)
- migrations (
[[migrate]]→E0234with afix:) + simulation ([sim]).
- migrations (
- Semver is enforced: the registry compares the API with the previous version (
P015). - Capabilities (
secure permissions push native network prefs links share deeplinks) are computed from the code; the manifest must match (P013); a person approves sensitive ones in[policy](P008);vard.lockrecords them. - Installation by exact names only (
P001with “did you mean”); the registry cuts off look-alike names (P010). - Namespaces without imports: own → direct dependencies → std; a conflict of two packages —
pkg.Name; transitive dependencies are invisible;_is private; native names are global. The linker renames conflicting declarations before type checking — the runtime knows nothing about packages.
Consequences. + an agent knows a package’s API and risks before installing, upgrades
mechanically, cannot install a guessed name or grant a package unapproved rights; adding a
package does not change the meaning of other code. − packages need an AGENT.md and an
example with tests; one version of a package per app (a consequence of the shared
namespace); capabilities limit “what”, not “how” (an approved network can still send data).
ADR-0006: Minimal version selection instead of a solver
Status: accepted
Context. Dependency solvers (npm, Cargo, pub, pip) pick the “newest compatible” version. The result depends on when they run; reproducibility comes from a lockfile, and losing or regenerating it changes behavior. Solver errors (“could not find a consistent set”) are hard to explain and fix — especially for a model. On top of that, a Vard app links one version of each package (a shared namespace), so version selection must be unambiguous.
Decision. Minimal version selection (as in Go modules). A requirement is a minimum on a
compatibility line ("1.4" = ≥ 1.4.0, < 2.0.0; 0.x lines are separate). Walk the
requirement graph from the app; for each package take the largest of the minimums;
requirements on different lines are P006, listing who wants what. Versions on a line are
published only in increasing order, so “the smallest existing version ≥ the minimum” is
stable. An upgrade is an explicit edit of the requirements in vard.toml (vard update),
visible in the diff.
Consequences. + the same result today, tomorrow and in CI, with or without a lockfile;
no backtracking; every error is explainable in one line; the lockfile only pins hashes and
capabilities. − new fixes do not arrive by themselves — vard update brings them; package
authors should raise their minimum requirements when they need a dependency’s fix.
ADR-0007: A static, content-addressed registry with a signed log
Status: accepted
Context. A registry must be cheap to host (for a team, a company, a community), work behind any CDN and through mirrors, and trust in packages must not depend on who serves them. Server-side read logic (search, version resolution) complicates mirroring and scaling.
Decision.
- The read protocol is static files:
config.json,catalog.json(the client searches),index/NAME.json(JSON lines, append-only),blobs/SHA256.vpk(immutable, cached forever). - The
.vpkarchive is deterministic (sorted paths, no metadata), so the hash is reproducible. - The publication log is a hash chain
log.txtwhose head is signed with ed25519 (log.head). A client pins the key on first contact and checks the signature, the chain, that the previously seen head is a prefix, and that every installed version is in the log. - Writes happen in one place and through one gate:
vard publish --registry DIR, CI over a git repository holding the registry, orvard registry serve(an HTTP publish API with tokens). - HTTPS goes through the system
curl, so the binary carries no TLS stack; integrity does not depend on the transport.
Consequences. + a registry is a directory served by anything; mirrors need no trust; substitution of an archive, the index or the history is detected by the client; one gate for every publishing path. − the client downloads the full log (for large registries, Merkle trees and inclusion proofs are on the roadmap); a mirror withholding updates is detectable only by comparing with another source.