Valdi

<h1 id="valdi">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./docs/docs/assets/branding/lockup-yellow-white.svg">
    <img width="320" src="./docs/docs/assets/branding/lockup-black.svg" alt="Valdi" />
  </picture>
</h1>

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Platforms](https://img.shields.io/badge/platform-iOS%20%7C%20Android%20%7C%20macOS-lightgrey)](./docs/INSTALL.md)
[![Status](https://img.shields.io/badge/status-beta-yellow)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?logo=typescript)](https://www.typescriptlang.org/)
[![Documentation](https://img.shields.io/badge/docs-available-brightgreen)](./docs/README.md)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)

> [!NOTE]
> **Beta Status:** Valdi has been widely used in Snap's production apps for the last 8 years. We're calling this a beta because our tools and documentation need more battle testing in the open source world. Valdi will exit beta when we're happy with the developer experience.

**Valdi is a cross-platform UI framework that delivers native performance without sacrificing developer velocity.** Write your UI once in declarative TypeScript, and it compiles directly to native views on iOS, Android, and macOS—no web views, no JavaScript bridges. 

## Quick Example

A basic Valdi component:

```tsx
import { Component } from 'valdi_core/src/Component';

class HelloWorld extends Component {
  onRender() {
    const message = 'Hello World! 👻';
    <view backgroundColor='#FFFC00' padding={30}>
      <label color='black' value={message} />
    </view>;
  }
}
```

<p align="center">
  <img src="./docs/docs/assets/start-about/IMG_1445.jpg" width="400" alt="Hello World example running on iOS" />
</p>

## Quick Start

**Prerequisites:** [Node.js](https://nodejs.org/) 20 or later (22 recommended) and, on macOS, Xcode 26.5 or 27. `valdi dev_setup` installs the rest. See the [Installation Guide](./docs/INSTALL.md#prerequisites).

```bash
# Install Valdi CLI
npm install -g @snap/valdi

# One-command setup (installs all dependencies)
valdi dev_setup

# Create your first project
mkdir my_project && cd my_project
valdi bootstrap
valdi install ios  # or android
```

> [!TIP]
> **Editor setup:** No Valdi-specific extension is needed. See [VSCode/Cursor setup](./docs/INSTALL.md#vscodecursor-setup-optional-but-recommended) to point your editor at the workspace TypeScript version.

## Quick Links

- [Getting Started Guide](./docs/INSTALL.md)
- [Documentation](./docs/README.md)
- [Codelabs](./docs/docs/start-code-lab.md)
- [API Reference](./docs/api/api-quick-reference.md)
- [Frequently Asked Questions](./docs/docs/faq.md)
- [Component Library](https://github.com/Snapchat/Valdi_Widgets)
- [GitHub Discussions](https://github.com/Snapchat/Valdi/discussions)
- [Roadmap](./ROADMAP.md)

## Example Apps

The [`apps/`](./apps) directory contains runnable examples:

| App | What i