# NativeDesktop

> One Rust view tree, native on macOS (AppKit), Linux and Windows (GPUI), and plain GPUI on the web.

Every page below is markdown. All of them in one file: https://native.formalsnake.dev/llms-full.txt. Building an app with nd: start at https://native.formalsnake.dev/agents/index.md.

## Start

- [NativeDesktop](https://native.formalsnake.dev/index.md): One Rust view tree that renders as native AppKit controls on macOS and through GPUI on Linux, Windows, and the web.
- [Getting started](https://native.formalsnake.dev/getting-started.md): Install the nd CLI, create an app, run it on the desktop and in a browser, and run its tests.

## Concepts

- [Programming model](https://native.formalsnake.dev/concepts/programming-model.md): Views, entities, and contexts, what render returns, and how the retained tree reaches a backend.
- [Elements](https://native.formalsnake.dev/concepts/elements.md): The element vocabulary: div, flex helpers, text, styling, layout, identity, and children.
- [State](https://native.formalsnake.dev/concepts/state.md): Entities and observation, controlled values, background work, clocks, errors, and saved state.
- [Actions and keys](https://native.formalsnake.dev/concepts/actions-and-keys.md): Declare actions, bind keys in contexts, build menus from the same actions, and move focus.
- [Theming](https://native.formalsnake.dev/concepts/theming.md): The design tokens apps read with cx.theme(), where their values come from on each OS, and how to change them.
- [Overrides](https://native.formalsnake.dev/concepts/overrides.md): Change how a native default looks or behaves, from one element's style up to the whole app, and pick the right layer for each change.
- [Patterns](https://native.formalsnake.dev/concepts/patterns.md): Declare window structure such as the toolbar, sidebar, inspector, and titlebar once, and let each OS draw it.
- [Native widgets](https://native.formalsnake.dev/concepts/native-widgets.md): Define your own widget with the NativeWidget trait: a drawn version for every OS, and a native view where the OS has one.
- [Swift](https://native.formalsnake.dev/concepts/swift.md): Add Swift to your app's macOS build when you need it, with a SwiftUI gauge as the worked example.

## Components

- [Components](https://native.formalsnake.dev/components/index.md): The built-in components by group: which ones are the OS's own control on macOS, which ones nd draws, and where to see each one.
- [Component reference](https://native.formalsnake.dev/components/reference.md): Every built-in element constructor and its builder methods, generated from nd-components.

## Guides

- [Virtualization](https://native.formalsnake.dev/guides/virtualization.md): Lists, tables, grids, and trees over keyed rows: ListState, versions, tail following, jump targets, selection, row actions, and how the macOS and GPUI presenters differ.
- [Overlays](https://native.formalsnake.dev/guides/overlays.md): Popovers, panels, tooltips, context menus, the command palette, and toasts: how they open and close, and why a click inside one never reaches the page or button under it.
- [Gestures](https://native.formalsnake.dev/guides/gestures.md): Tap, double tap, long press, and drag; trackpad pinch, rotate, and page swipes; momentum scrolling, haptics, and the focus rules that go with them.
- [Motion](https://native.formalsnake.dev/guides/motion.md): Platform timings for every animation, hover groups that reveal actions, shared element transitions, presentations, and the lyrics depth of field.
- [Windows and tabs](https://native.formalsnake.dev/guides/windows-and-tabs.md): Open windows with WindowOptions, use several windows and monitors, place window controls and drag regions, group window tabs with tab_group, and use the in-window tab, split, and pane widgets.
- [Webview](https://native.formalsnake.dev/guides/webview.md): Show web pages in a window with WebView and webview(): the app-owned handle, commands, events, WKWebView and CEF, the Linux setup, and what Windows doesn't have yet.
- [Terminal](https://native.formalsnake.dev/guides/terminal.md): Show a shell or any byte stream in a window with nd-terminal: TerminalSession, terminal(), theme colors, input, and what runs on each OS.
- [System](https://native.formalsnake.dev/guides/system.md): Use dialogs, the clipboard, notifications, the keychain, a tray icon, media keys, audio, and OS events through nd::system, and add plugins for anything the framework doesn't ship.
- [Settings and config](https://native.formalsnake.dev/guides/settings-and-config.md): The app manifest, user settings as a TOML file with layers and Nix support, machine state, local sockets, and SQLite.
- [Packaging](https://native.formalsnake.dev/guides/packaging.md): Build installers for macOS, Linux, and Windows with nd package, and ship signed delta updates from a static feed with nd release.
- [Web](https://native.formalsnake.dev/guides/web.md): Build the same app for the browser with nd build --target web: one canvas, the plain GPUI look, and checks for what a browser can't do.

## Tooling

- [The nd command](https://native.formalsnake.dev/tooling/cli.md): Every nd subcommand, its flags, and one example of each.
- [Testing](https://native.formalsnake.dev/tooling/testing.md): The three test tiers, goldens, real input, the nd-test locators, the MCP bridge, and how nd test runs them.
- [Diagnostics](https://native.formalsnake.dev/tooling/diagnostics.md): What nd-diag records in every app without code, and how to read an incident bundle after a panic, crash, or hang.
- [Performance](https://native.formalsnake.dev/tooling/performance.md): The frame budgets that nd apps hold, the numbers measured so far on e1504g, g815, and the macbook, and how to measure your own app.

## For agents

- [For agents](https://native.formalsnake.dev/agents/index.md): What a coding agent gets from nd new, and how to point one at an nd project.
- [Patterns](https://native.formalsnake.dev/agents/patterns.md): How an nd app is put together: system structure, entities, actions, controlled values, overlays, and time.
- [Widgets](https://native.formalsnake.dev/agents/widgets.md): Which element to use, virtual lists, and app-defined native widgets that never echo.
- [Testing](https://native.formalsnake.dev/agents/testing.md): The three test tiers, the machine lock, and reading the incident bundle before reproducing a bug.
- [Styling](https://native.formalsnake.dev/agents/styling.md): Theme tokens, the appearance audit, override layers, and glass.
- [Performance](https://native.formalsnake.dev/agents/performance.md): Budgets on the slowest machine, per-view rendering, and keeping the main thread free.
- [Don'ts](https://native.formalsnake.dev/agents/donts.md): The hard list, with the nd check rule that fires for each.

## Examples

- [Examples](https://native.formalsnake.dev/examples.md): Every example app in the repository, running live on the web and captured on each OS.