# zgx

> A retained-mode GUI framework in Rust for macOS, Windows and Linux, with Luau scripts that hot reload. Every page below is also Markdown at its URL plus `.md`; all of them in one file: /llms-full.txt.

## zgx

The Rust framework: views, layout, text, windows

- [Overview](https://zgx.zeron.sh/rust.md): A retained-mode GUI framework in Rust for macOS, Windows and Linux.
- [Getting started](https://zgx.zeron.sh/rust/getting-started.md): From nothing to a window, a list, selectable text, a settings window and a shipped app, in Rust.
- [Desktop applications](https://zgx.zeron.sh/rust/application.md): macOS, Windows and Linux are the target platforms.
- [Components and composition](https://zgx.zeron.sh/rust/composition.md): Application code should describe a tree of components and children.
- [Layout](https://zgx.zeron.sh/rust/layout.md): Build children with div, row, column, and reusable functions or components.
- [Styling](https://zgx.zeron.sh/rust/styling.md): zgx's Rust API combines GPUI/QuickGUI-style fluent methods with owned component children.
- [Paint styles](https://zgx.zeron.sh/rust/paint-styles.md): Gradients, brushes, per-corner radii, per-edge borders, border styles and layered shadows.
- [Rich text](https://zgx.zeron.sh/rust/rich-text.md): A rich paragraph shapes all inline spans together.
- [Canvas](https://zgx.zeron.sh/rust/canvas.md): Retained drawing in a styled view: paths, fills and strokes, redrawn only when what they read changes.
- [Images and animation](https://zgx.zeron.sh/rust/images-and-animation.md): ImageCache::load(key, fetch) shares one pending application-supplied future among requests for that key.
- [Image transforms](https://zgx.zeron.sh/rust/image-transforms.md): Rotate, scale, reflect, shear and translate images and SVG about their centre, as paint.
- [Actions and key bindings](https://zgx.zeron.sh/rust/actions.md): Components register keyboard bindings and action handlers without owning the native event loop.
- [Scoped tasks](https://zgx.zeron.sh/rust/scoped-tasks.md): WindowContext.tasks.spawn runs until completion or its window closes.
- [Popups, drags and windows](https://zgx.zeron.sh/rust/multi-window.md): On macOS a zgx app's menus, drags and windows behave as AppKit's do, past the edges of their window and between windows.
- [Drag and drop](https://zgx.zeron.sh/rust/drag-drop.md): Typed drags between views and windows: previews, spring-loaded targets, file drops, and drags out to other apps.
- [Dialogs and menus](https://zgx.zeron.sh/rust/platform-services.md): WindowContext::dialogs provides asynchronous open-file, open-files, open-folder, open-folders, and save-file selection.
- [Architecture](https://zgx.zeron.sh/rust/architecture.md): The implementation has a platform-independent Rust core, a retained wgpu renderer, a software reference renderer, and a native desktop host.
- [Changelog](https://zgx.zeron.sh/rust/changelog.md): What changed for apps, newest first, with how to migrate.
- [Releasing](https://zgx.zeron.sh/rust/releasing.md): zgx 0.1.0 is on crates.io (2026-10-25, tag v0.1.0).

## zgx-script

Luau apps that hot reload, and the API reference

- [Overview](https://zgx.zeron.sh/luau.md): Interfaces from Luau scripts: built once, lowered to retained views, hot reloaded with their state kept.
- [Getting started](https://zgx.zeron.sh/luau/getting-started.md): From nothing to a window, a list, selectable text, a settings window and a shipped app, in Luau.
- [Coming from React](https://zgx.zeron.sh/luau/coming-from-react.md): zgx scripts describe an interface the way React does: functions return elements, state drives what shows, lists have keys.
- [App structure](https://zgx.zeron.sh/luau/app-structure.md): A small app is one file.
- [Types, check and lint](https://zgx.zeron.sh/luau/types-and-lint.md): Type check scripts with zgx check, catch costly patterns with zgx lint, and read what a reload reports.
- [Elements](https://zgx.zeron.sh/luau/elements.md): What a script builds from: boxes, text, controls, web views, terminals, state, plugins, testing and shipping.
- [Theming](https://zgx.zeron.sh/luau/theming.md): Theme tokens, light and dark, and the system’s accent, contrast and text size.
- [Animation](https://zgx.zeron.sh/luau/animation.md): anime.js v4’s API on a Rust engine that ticks once per display frame and sleeps at rest.
- [Design systems](https://zgx.zeron.sh/luau/design-systems.md): A design system in zgx is three layers: theme tokens hold the values ("$accent", "$space.3"; see theming), ui.variants turns them into each component's styles, and the design lint keeps code from going around them.
- [Reading the reference](https://zgx.zeron.sh/luau/reference.md): One page per element and API group of zgx-script.
- [API index](https://zgx.zeron.sh/luau/reference/api.md): Every function and value of ui and anime, with the type luau-lsp checks it against, read from zgx.d.luau when the site builds.
- [State and components](https://zgx.zeron.sh/luau/reference/state.md): State is Rust-owned and keyed, so a reload keeps it.
- [Properties](https://zgx.zeron.sh/luau/reference/properties.md): What every element takes besides its children and its own options.
- [Events](https://zgx.zeron.sh/luau/reference/events.md): Handlers any node takes: pointer, keyboard, focus, lifecycle, and drag and drop within the window.
- [Containers](https://zgx.zeron.sh/luau/reference/containers.md): Boxes that lay out their children.
- [Controls](https://zgx.zeron.sh/luau/reference/controls.md): Controls take keyboard focus, show it with an accent ring, and (except button) bind a state both ways: the control shows the state, and the user's changes write it.
- [Text](https://zgx.zeron.sh/luau/reference/text.md): ui.text shows one string in one style; ui.rich shows runs of differently styled text (ui.spans) as one paragraph.
- [Dynamic content](https://zgx.zeron.sh/luau/reference/dynamic.md): Parts of the tree that follow state.
- [Scrolling and lists](https://zgx.zeron.sh/luau/reference/scrolling.md): scroll and scroll_x are viewports over ordinary children, all of them mounted.
- [Overlays and menus](https://zgx.zeron.sh/luau/reference/overlays.md): Panels over the interface.
- [Images and canvas](https://zgx.zeron.sh/luau/reference/media.md): Pixels from files, vector icons, and drawing in script.
- [Web views and terminals](https://zgx.zeron.sh/luau/reference/native.md): Native content laid out as nodes, and the app's menu commands.
- [anime and bindings](https://zgx.zeron.sh/luau/reference/anime.md): The anime global follows anime.js v4's API; animations run in a Rust engine that ticks every playing animation once per display frame and asks for no frames at rest.

## Platforms

macOS, Windows and Linux hosts, and their checks

- [Overview](https://zgx.zeron.sh/platforms.md): One app on macOS, Windows and Linux, and what each desktop host does differently.
- [Windows](https://zgx.zeron.sh/platforms/windows.md): Use stable Rust with the x86_64-pc-windows-msvc target and Visual Studio Build Tools (Desktop development with C++, including the Windows SDK).
- [Linux](https://zgx.zeron.sh/platforms/linux.md): zgx runs natively on Wayland and on X11 (winit picks Wayland when WAYLAND_DISPLAY is set).
- [Window controls](https://zgx.zeron.sh/platforms/window-controls.md): WindowContext::window is a cloneable, thread-safe WindowHandle.
- [CoreVideo surfaces (macOS)](https://zgx.zeron.sh/platforms/native-surfaces.md): Show CoreVideo frames as a retained, styled view, fitted like an image.
- [Validation record](https://zgx.zeron.sh/platforms/validation.md): Development checks run on Linux x86_64.

## Devtools

Drive a running app from a shell or over MCP

- [zgx inspect](https://zgx.zeron.sh/devtools.md): See and drive a running zgx Luau app: its tree, states and errors; clicks, typing and keys.
- [Targets](https://zgx.zeron.sh/devtools/targets.md): One selector syntax for every command and for Rust tests: #id, "name", role:, @n, >>, row n, [n].
- [Reading](https://zgx.zeron.sh/devtools/reading.md): tree, node, find, state, errors, lint, frames and snapshot: what is on screen and why.
- [Acting](https://zgx.zeron.sh/devtools/acting.md): click, type, key, scroll, command, set, wait and sleep.
- [Record and replay gestures](https://zgx.zeron.sh/devtools/gestures.md): Record a trackpad gesture once, replay it through the window’s own input path, and read how its frames landed.
- [MCP server](https://zgx.zeron.sh/devtools/mcp.md): zgx inspect mcp serves every command as an MCP tool on stdio.
- [Diagnose a slow interaction](https://zgx.zeron.sh/devtools/slow-interactions.md): Find what runs on each frame of a stutter, which script line made it, and what to write instead.
- [Recipes and safety](https://zgx.zeron.sh/devtools/recipes.md): Common sequences, and what serving devtools costs and exposes.
- [CLI reference](https://zgx.zeron.sh/devtools/cli.md): Every command of zgx and zgx-run, as their --help prints it, with exit codes and the lint rules.
- [Profiling](https://zgx.zeron.sh/devtools/profiling.md): ZGX_PROFILE splits a frame by phase; the perf suite compares two revisions in retired instructions.

## Performance

Against GPUI, MyGo and Rune, trial by trial

- [Results](https://zgx.zeron.sh/performance.md): zgx against GPUI Fast, MyGo and Rune on one Mac, in one session, the same four scenes built from the same workload code.
- [Microbenchmarks](https://zgx.zeron.sh/performance/microbenchmarks.md): One state change, and one scroll step of 10,000 rows, timed headless in process CPU per operation, from the change to a frame ready to present.
- [zgx and GPUI](https://zgx.zeron.sh/performance/gpui.md): The heavy dashboard in zgx, GPUI and GPUI’s fast path on an Apple Silicon Mac, with and without PGO.
- [Methodology](https://zgx.zeron.sh/performance/methodology.md): The three adapters use the same comparisons/workload Rust crate.