Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

PageWhat it covers
Getting startedinstall, first project, the “edit → check → run → test” loop
Working with AI agentshow the AI-first approach works: AGENTS.md, skills, MCP, token budget

Guide

PageWhat it covers
The Vard languagetypes, declarations, views, the UI tree, expressions, mutability, functions
UI: elements, layout, stylebuilt-in elements, flex/grid, common props, tokens, themes, dark mode
Reactivity and execution modelsignals/computed/effects, keyed lists, rules for pure rendering
Platform and native moduleslifecycle, back, insets, permissions, storage, push, extern fn/extern event
Testing and debuggingheadless runs, the action language, .vtest, why, lints, the platform simulator
Tooling: CLI and MCPevery vard command, the MCP server, output formats
DiagnosticsE/W/R/L/P codes, how to read and fix them

Packages, registries and delivery

PageWhat it covers
Package system overviewthe idea and key decisions: a contract computed by the compiler
Using packagesvard search/add/update, vard.toml, vard.lock, namespaces, the capability policy
Writing a packagelayout, manifest, AGENT.md, the example as proof, migrations, native code, publishing
Registries and hostingprotocol, file formats, vard registry serve, CDNs, registries in git, private registries
Delivery to devicesvard bundle, the native fingerprint, Android, over-the-air updates
Security modelthreats (including LLM-specific ones) and defenses

Platforms and architecture

PageWhat it covers
Architecturelayers, decisions, roadmap
Android shellbuild, Gradle properties, native modules
ADRsarchitecture 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

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

PrincipleHow it is implemented
Write it right the first timea small regular language, syntax close to Swift/Kotlin/TS, one form for each thing
Fix without thinkingevery 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 visiona semantic tree ≈ 100 tokens; actions print diffs; why explains sizes; lints describe the recipe
Knowledge from one sourcethe reference is compiled into the binary and generated from the element registry — it cannot drift from the compiler
Determinismheadless runtime, bundled font, platform simulator, MVS for versions: same inputs, same result
A person decides outward-facing and risky stepsapproving package capabilities and publishing are not available through MCP

What an agent gets in a project

vard new creates:

  • AGENTS.md (and CLAUDE.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 — the vard mcp server.

Token budget

OperationCost
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 updatean API diff + --fix instead of reading a changelog
  1. Once per session — vard doc (or vard_doc).
  2. Edit .vard → vard check --fix → fix the rest.
  3. vard run --do "…" — the screen and actions; why for sizes, state/log for values.
  4. A test for every feature and bug: tests/*.vtest, vard test.
  5. Need “library” functionality — vard search → vard info → vard add → vard doc NAME. Never guess names; on P008, ask the user.
  6. 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 run mounts 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 error E0106 with 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

TypeExampleNotes
Int4264-bit integer; Int / Int truncates
Float3.5Int converts to Float implicitly; back with toInt()
String"Count: {n}"interpolation {expr}; escapes \n \t \" \\ \{ \}
Booltrue
Color#RGB #RRGGBB #RRGGBBAAor a token such as .primary
[T][1, 2]list
[String: T]["a": 1], [:]map; keys are always String (E0125)
T?niloptional
fn(A, B) -> Rx => x * 2function
struct/enumTodo(id: 1, title: "A"), .activeuser-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

FormMeaning
name: Type [= default]read-only; reactive — updates when the caller’s value changes
bind name: Typetwo-way: the caller passes a mutable place (Checkbox(value: todo.done))
name: slota 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 key vard.pref.<name> and restored at launch. Any data type (structs, lists, maps). All prefs 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

TypePropertiesMethods
Stringcount isEmptytrim() upper() lower() contains(s) startsWith(s) endsWith(s) split(sep) toInt() toFloat()
InttoFloat() toString() abs()
FloattoInt() round() floor() ceil() abs() fixed(digits)
[T]count isEmpty first lastcontains indexOf map filter find any all sum join sortedBy reversed; in place: append insert removeAt remove removeWhere clear
[String: T]count isEmpty keys valuescontains(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 current locale (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 use t().
  • 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 ru action.

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

ElementPropsMeaning
Column / Rowgap align justify (+ wrap on Row)flex containers; Row(wrap: true) flows children onto new lines
Gridcolumns gap alignequal columns, filled row by row
Stackalign justifychildren overlap; z-order = source order; a grow child fills the height
Scrollgap aligna vertically scrolling column; needs a bounded height (grow: 1)
Text(text)style size weight color textAlign maxLines strike underline italic font letterSpacing lineHeighttext
Inputvalue (bind String) placeholder onSubmit onChange secure keyboard size weight font color placeholderColortext field; on devices a native editor over the frame
Image(src)fit tinta project file ("assets/logo.png") or an https URL
Spacerflexible 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; alignSelf overrides align for a child.
  • Sizes: width height minWidth minHeight maxWidth maxHeight aspectRatio.
  • Spacing: padding paddingX paddingY paddingTop paddingBottom paddingLeft paddingRight; safeArea: .top|.bottom|.all|.vertical|.horizontal adds 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/.muted on .background/.surface, .onPrimary on .primary. Contrast below WCAG AA is lint L005.
  • 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 global isDark; in tests — theme dark or @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:

CodeWhat
L001children overflow their container (needs a Scroll, or grow: 1 on the flexible child)
L002an interactive element smaller than 44×44 dp
L004a container with children has zero width or height
L005text contrast below WCAG AA
L006a 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 codeIn the runtime
state x, pref xSignal — a cell with a list of subscribers
let y = ..., view parametersComputed — a lazy cached value; dependencies are collected on read
every dynamic propEffect — writes one field of one node
if / for in the treea structural Effect over a fragment of the tree
a viewScope — 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

  1. Rendering is pure. Writing state while computing a prop, a let or an if/for condition is R0003. Writes go into handlers (onTap, onChange, onSubmit, on event) and functions called from them.
  2. A let does not read itself (R0004), directly or through other lets.
  3. Values are copied. let t = todos[0]; t.title = "x" does not change the list; change the place: todos[0].title = "x".
  4. Keys are unique. R0002 — two equal by keys.

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

  1. 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)
    
  2. Build the UI and test it headless (mock, resolve, emit — see Testing).
  3. Generate typed Kotlin: vard bindings --kotlin --class PlacesModule --out ... and implement the abstract methods (callbacks may be answered from any thread; send() instead of resolve() for listeners).
  4. 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 one vard 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.

ActionWhat it does
treethe semantic tree with @ids (the default)
layoutevery node with [x,y WxH], style and file:line
tap SEL · type SEL "text" · submit SEL · focus SEL · scroll SEL DYinteraction
why SELwhy the element has this size and position — up the parent chain
find SEL · state · log · stats · lintinspection
expect SEL · expect "text" · expect no "text"assertions
expect SEL checked|unchecked|enabled|disabled|offscreen|visibleelement state
theme light|dark · size W H · insets T B [L R] · keyboard H · locale TAGenvironment
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

  1. vard check → errors with fixes (--fix applies them to a fixed point).
  2. vard run --do tree → the screen as text.
  3. Actions print only the changes.
  4. why/layout give the numbers and the rule that produced a size.
  5. lint: lines and ! Rxxxx are real bugs — fix them first.
  6. 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

CommandWhat 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 CODEexplains an E/W/R/L/P code
vard new NAMEa 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

CommandWhat it does
vard search WORDSsearch 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.vpkeverything 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 OWNERa 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 DIRhand the registry over to a new signing key (signed by the old one)
vard registry verify DIR|URLverify 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.mcpb on 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.
ToolEquivalent
vard_checkvard check (fix: true)
vard_runvard run --do
vard_screenshota PNG after actions (expensive in tokens — only to judge design)
vard_testvard test
vard_docvard doc (including package docs)
vard_explainvard explain
vard_search, vard_infosearch and a package card
vard_addvard add without --allow: approving a sensitive capability is a person’s decision
vard_updatevard update with the API diff
vard_apivard api
vard_publish_checkthe publish gate without publishing
vard_bindingsvard 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

PrefixWhereExamples
E01xxsyntaxE0106 stray ;, E0110 a foreign keyword, E0111 an import, E0119 a modifier chain
E02xxnames, elements, props, packagesE0201 unknown element, E0202 unknown prop, E0203 unknown name, E0206 missing required argument
E03xxtypesE0301 type mismatch, E0304 unknown enum variant, E0314 optional not unwrapped, E0317 cannot cross the native boundary
E04xxmutabilityE0401 assignment to something immutable, E0402 in-place method on an immutable list
W04xxwarningsW0401 loop without by, W0403 Input without value
Rxxxxruntime (printed as ! R0003 … (file:line))R0003 state written during render, R0010 no native implementation
LxxxUI lintsL001 overflow, L002 small tap target, L005 contrast
Pxxxpackages and registries (location: a line of vard.toml)P001 no such package, P008 policy, P015 semver

Packages in the compiler (E023x)

CodeMeaningWhat to do
E0230a _ name is private to its packageuse the public API (vard doc PACKAGE)
E0231two direct dependencies export the namequalify it: charts.Badge(...)
E0232the name comes from a package that is not a direct dependencyvard add NAME
E0233two sides declare the same native nameremove the duplicate or rename it on both sides
E0234a name/parameter was renamed in a newer package versionvard check --fix
E0235pkg.Name: no such package or no such public namecheck the name; a typo comes with a fix:

Package manager (P0xx)

CodeMeaning
P001no package with this name; “did you mean” lists real names
P002the registry is unreachable or is not a Vard registry
P003no version satisfies the requirement
P004integrity failure: the archive hash differs, or the version is not in the signed log
P005the registry key changed or the log history was rewritten
P006incompatible requirements for one package (different major lines)
P007the package needs a different vard core version
P008a sensitive capability is not approved in [policy]
P009the version was yanked
P010an invalid, reserved or too-similar-to-someone-else’s name
P011no AGENT.md, or it exceeds the 6 KB budget
P012the package does not compile
P013declared capabilities differ from the computed ones
P014the package’s tests failed
P015the version number does not match the API change
P016the version is already published or is not newer than the latest on its line
P017[sim] refers to an undeclared extern
P018no token, or not the owner’s token
P019the archive is larger than 8 MB
P020vard.toml is not valid TOML (the subset Vard uses)
P021a wrong or unknown field in vard.toml
P022the project’s packages are missing or out of date
P023a minor/patch release fails the previous version’s tests (behavior changed)
P024the package is new (first published < 72 h ago): a person confirms with --allow-new
P025a 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:

  1. 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.
  2. 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.
  3. 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

PartWhat it isWho produces it
Code.vard sources, optionally a native module and resourcesthe author
Contractthe public API and capabilitiesthe compiler — computed from code, not declared
KnowledgeAGENT.md ≤ 6 KB (≈ 1500 tokens) + the generated API + skillsthe author + the compiler
Proofheadless tests of example/ and the package, run by the registry at publishthe registry
Migrationsrenames that become fix:es for consumersthe author
Simulation[sim] answers for the package’s externs in headless modethe 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 an extern fn, subscribe to pushReceived or load https://. The manifest must match what was computed (P013); the consumer must approve sensitive capabilities in [policy] (P008); vard.lock records them, so a new capability in a dependency is a line in a code-review diff.
  • Upgrades are mechanical. vard update prints the API diff, and vard check --fix applies the package’s migrations to the app’s code (E0234). The agent does not read a changelog.
  • Installation never guesses. vard add installs 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 doc shows the project’s packages one line each; vard doc NAME shows AGENT.md and the generated API. The document budget is checked at publish (P011). The package block in the project’s AGENTS.md is 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 working vard run right after vard 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:

  1. an unqualified name is looked up in its own package (the app is a package too), then in direct dependencies, then in std;
  2. your own declarations always win over packages;
  3. if two direct dependencies export a name — E0231, write pkg.Name;
  4. transitive dependencies are invisible (E0232), _ names are private (E0230);
  5. extern fn/event names 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 fieldsmigrations 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 provenancesigned build attestations (Sigstore)
quarantine of new remote packages (--allow-new)—
static registry, signed log, key pinning, prefix check, signed key rotationMerkle inclusion proofs instead of the full log (needed beyond ~100k versions)
vard registry serve with token-based publishing, yank; a web page in every registryorganizations 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 Androidan 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)
}
SituationWhat happens
a name is both in your code and in a packageyours wins; the package keeps using its own internally
two direct dependencies export a nameE0231 — write charts.Badge(...) or tailwind.Badge(...)
a name from a transitive dependencyE0232 — add it explicitly (vard add NAME)
a _ name from someone else’s packageE0230 — private
a pkg.Name that does not existE0235, with a fix for a typo
two dependencies declare one native nameE0233

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

CapabilityMeaningSensitive
prefsreads/writes preferences (pref, prefGet)
linksopens URLs in other apps
sharethe system share sheet
deeplinksreceives deep links
secureKeychain / Keystore✓
permissionsasks for runtime permissions✓
pushtoken, notifications, push events✓
networkloads remote resources (https:// in code)✓
nativedeclares 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 how tailwind works).

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:

  1. one sentence — what it is and when to use it;
  2. the main views/functions — one compiling example each;
  3. non-obvious rules (what goes into a bind, which tokens to use);
  4. how to test headless: what [sim] answers, what needs resolve/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:

  1. declare the API in Vard in the package’s sources;
  2. generate a base class: vard bindings charts/ --kotlin --package dev.example.charts --class ChartsModuleBase;
  3. put an Android library into native/android/ (build.gradle.kts, an AndroidManifest.xml with <meta-data android:name="dev.vard.module.charts" android:value="dev.example.charts.ChartsModule"/>, the Kotlin implementation);
  4. add [native.android] to the manifest;
  5. 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:

ChangeMinimal step
a name, parameter, field or enum variant removedmajor
a type, bind, return value or the first (positional) parameter changedmajor
a parameter became required; a required parameter or a field without a default addedmajor
a name, enum variant, or a parameter/field with a default addedminor
nothing in the APIpatch

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; the check workflow runs vard publish --dry-run with the PR author as the owner. After a merge, the publish workflow publishes as the PR author, removes the submission, commits public/ 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

RequestResponseCaching
GET config.jsonname, protocol version, public keyshort
GET catalog.jsonthe catalog for search (search runs on the client — the server computes nothing)short
GET index/NAME.jsonevery version of a package; 404 — no such packageshort
GET blobs/SHA256.vpkan archiveforever (immutable): the address is the content hash
GET log.txt, GET log.headthe signed logshort

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:

  1. pins its key (~/.vard/known_registries, like SSH’s known_hosts); a changed key is P005;
  2. verifies the head’s signature and recomputes the chain;
  3. checks that the head it saw last time is a prefix of the new log (history was not rewritten) — P005;
  4. 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 from public/; archives with Cache-Control: immutable.
  • POST /api/v1/publish — body: a .vpk, header Authorization: Bearer TOKEN. The server unpacks the package into a scratch directory, runs the same gate as vard publish (compile, tests, semver, capabilities…) and appends to the log. The response is the gate report.
  • POST /api/v1/yank — body NAME 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

WhereWhat
vard.toml [registries]the project’s registries and default
~/.vard/config.toml [registries]the user’s registries (default = "acme")
VARD_REGISTRYthe default registry for every project (CI)
~/.vard/credentials.toml [tokens] acme = "vard_…" or VARD_TOKENpublish tokens
~/.vard/known_registriespinned 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 .vpk format).
  • native_fingerprint — the hash of the sorted list of everything that must exist in the native part: extern fn and extern event names 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:

  1. settings.gradle.kts runs vard android-modules <vard.app> — the list of packages with [native.android] — and includes each library as :vard-<name>; :app depends on them;
  2. the bundleVardApp task runs vard bundle <vard.app> --out build/generated/vardAssets/app;
  3. VardActivity reads *.vard and vard.lock from the assets; modules register through dev.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.

ChangeFingerprintDeliverable OTA
layout, logic, styles, textssameyes
a new version of a package without native codesameyes
a new extern fn / extern event or a new native moduledifferentno — 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:

  1. downloads <its own fingerprint>/latest.json and the bundle it names (static hosting, any CDN);
  2. calls vard_ota_install(latest, bundle, len, key, fingerprint, dir) (C ABI; Rust vard_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 to dir atomically; any failure leaves the current bundle in place;
  3. loads dir instead 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.toml gives the same version selection (MVS); vard.lock pins the hashes.
  • .vpk archives are deterministic: sorted paths, no timestamps, no permissions.
  • vard bundle gives the same sha256 for the same inputs on any machine.
  • Offline: packages from the cache (~/.vard/cache/), builtin and 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

ThreatDefenseCode
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 guessingP001
Typosquatting (tailwnd, charts ↔ chart)the registry refuses a name one edit away from an existing name of another owner, and reserved wordsP010
A freshly registered malicious packagequarantine: 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 NEWP024
A package silently gains access to secrets, permissions, the network, native codethe compiler computes capabilities; the manifest must match; sensitive ones need [policy] allow; the MCP tool cannot approveP013, P008
An update gives a package a new capabilityvard.lock stores caps=; the change is a ! line in the report and in the diff; without approval installation is refusedP008
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/CDNcontent addressing: the archive is checked against the sha256 of the index and the lockfileP004
The index substitutedthe (name, version, sha256) entry must be in the signed logP004
The whole registry substituted / MITMthe public registry’s key is compiled into vard; other registries’ keys are pinned on first contact; a changed key is an errorP005
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 immutableP005, P016
A package breaks other code by “capturing” namesyour own names win; transitive dependencies are invisible; a conflict of two packages needs explicit qualificationE0231, E0232
Two packages claim one native functionnative names are global, a conflict is a compile errorE0233
A false “backward compatible”semver is computed from the API diff, and the previous version’s tests must pass against a minor/patch releaseP015, 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 errorsP005
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 limitP012, P014, P019
Prompt injection through a package’s docsAGENT.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 tokenonly sha256(token) is stored; a token is bound to its owner; yank to withdraw versionsP018

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 network can send data. The approval is a person’s decision; vard info shows why each capability is needed.
  • Native code. The native capability 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.lock and watch caps= and sha256= in diffs.
  • In CI: vard install (without --allow) fails if someone added a dependency with an unapproved capability; run vard registry verify URL periodically.
  • Keep a registry’s private/ out of public hosting; keep the key in CI secrets.
  • For agents: the vard-packages skill already contains the rule “on P008, stop and ask the user”.

VardUI architecture

Goals and their consequences

GoalConsequence in the design
AI writes the code right the first timea 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 thinkinga 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 screenshotsa semantic tree with @ids, diffs after actions, why for sizes, state, lints with a ready recipe
minimal tokenscompact 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
performancefine-grained reactivity: a view body runs once, then exactly the prop whose dependencies changed is updated; single-pass layout
extensibilitydesign systems = plain Vard views (std is written that way); native functions = extern fn, platform events = extern event; elements = registry entries
an ecosystem for agentspackages 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 ;, ===, @State and 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, .primary and lambda parameters are inferred without annotations. The Unknown type 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 doc is generated from it too.

Packages: linking, API, capabilities (vard-lang)

  • link.rs — namespaces without imports. Package files arrive with @name/... paths, the graph comes from vard.lock (or a LinkInfo from the CLI, with migrations). Resolution order: own → direct dependencies → std. Conflicting package declarations are renamed to pkg.Name before type checking, so the checker and the runtime work with unique names and know nothing about packages. Errors E0230–E0235; package migrations become E0234 with 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, let and 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 of Scopes: 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 the by key; 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 — why prints 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 R diagnostic with file:line, the value becomes nil. 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) and extern event (platform → app; on name(...) [if cond] { } handlers live while the view is on screen). Only data crosses (structs, enums, lists, maps, optionals) and callbacks fn(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 the firebase package returns a JSON document, and Vard turns it into a Profile or Note struct — whatever the developer declared.
  • Callbacks — functions in arguments become {"$callback": id}; the host answers with callback(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, events appear/back/appResume/appPause/deepLink/push*, globals safeArea, keyboardHeight, backProgress, isDark, screenWidth.
  • Headless — Sim in 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, restart models a cold start. User externs answer with a mock value or stay pending until resolve/send; packages’ [sim] sets defaults.
  • pref — state the runtime persists through the same boundary (prefGet/prefSet with the key vard.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; safeArea adds them to padding. If the code never mentions safeArea, the runtime pads the root itself (a static flag from the checker). on back if cond tells 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 (Android Paint.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

  1. vard check → errors with fixes. 2. vard run --do "tree" → the screen as text.
  2. Actions print only the changes. 4. why/layout give 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:

  1. 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) and platforms/android (the :vard library with VardActivity, the :app shell, the firebase package’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 and onTap bubbling stay in the core, Input is a native EditText over the Canvas. A mutation buffer instead of the full frame is the next step.
  2. 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.
  3. 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.
  4. Native modules. Done: extern fn with callbacks, extern event + on, the std platform (permissions, push, prefs, secure storage, back, insets), vard bindings --kotlin and --swift (the Swift output is type-checked by swiftc in 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/await sugar over callbacks.
  5. Language. Done: Map, pref, Grid, wrap, shadows/gradients/fonts, localized text (strings tables, t(), the locale global — checked at compile time). Next: navigation as a built-in element (today a stack + on back pattern), 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.
  6. Accessibility. The semantic tree exists — mapping it to TalkBack/VoiceOver.
  7. On-device inspection. Done: the action protocol over TCP (vard run --device), a listener in vard-ffi that runs scripts on the UI thread, enabled in debuggable Android builds. Next: a device parameter for the MCP tools.
  8. 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 bundle with 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

FeatureHow it works
Edge-to-edgethe 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 backandroid: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
PermissionsPermissionsModule: requestPermissions + shouldShowRequestPermissionRationale → granted/denied/blocked; a permission missing from the manifest is denied with a hint in logcat
PreferencesPrefsModule over SharedPreferences; pref variables are stored there too
KeychainSecureModule: AES-256-GCM, the key never leaves the Android Keystore
Notifications and pushVardPush: 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 linksappResume/appPause, deepLink(url) for vard://...
Modulesthe core ones + every library with <meta-data android:name="dev.vard.module.<name>" android:value="<class>"/> + the app’s modules()
Fonts and imagesthe 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

ComponentVersionWhere to get it
Rustfrom rust-toolchain.tomlrustup target add aarch64-linux-android x86_64-linux-android
cargo-ndk4.xcargo install cargo-ndk --locked
Android SDKplatform 35, build-tools 35Android Studio → SDK Manager
NDK28.2.13676358 (ndkVersion in vard/build.gradle.kts)SDK Manager → SDK Tools → NDK (Side by side)
JDK17–21e.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
PropertyDefaultMeaning
vard.appexamples/todowhich Vard project to package (path from the repository root)
vard.abisarm64-v8a,x86_64ABIs for cargo ndk -t; for an emulator -Pvard.abis=x86_64 is enough
vard.skipCargofalsedo not call cargo, take prebuilt .so files from vard/src/main/jniLibs/<abi>/
vard.applicationIddev.vard.hostthe 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)

  1. Declare the API in .vard: extern fn searchPlaces(query: String, done: fn([Place], String?)), extern event locationChanged(lat: Float, lng: Float).
  2. Generate a typed base class: vard bindings examples/myapp --kotlin --package com.example --class PlacesModule --out app/src/main/kotlin/PlacesModule.kt.
  3. 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 the firebase package 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

ADRDecision
0001Our own Vard language instead of a DSL in Kotlin/Swift/TS
0002Fine-grained reactivity without a virtual DOM
0003Text inspection as the primary debugging interface
0004A knowledge base for agents, in English, compiled into the tool
0005Packages with a contract computed by the compiler
0006Minimal version selection instead of a solver
0007A 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.

  1. 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]] → E0234 with a fix:) + simulation ([sim]).
  2. Semver is enforced: the registry compares the API with the previous version (P015).
  3. 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.lock records them.
  4. Installation by exact names only (P001 with “did you mean”); the registry cuts off look-alike names (P010).
  5. 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.

  1. 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).
  2. The .vpk archive is deterministic (sorted paths, no metadata), so the hash is reproducible.
  3. The publication log is a hash chain log.txt whose 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.
  4. Writes happen in one place and through one gate: vard publish --registry DIR, CI over a git repository holding the registry, or vard registry serve (an HTTP publish API with tokens).
  5. 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.