quickgui 0.1.0

A damage-driven, GPU-accelerated desktop GUI foundation
Documentation
# QuickGUI

QuickGUI is a damage-driven, GPU-accelerated GUI framework for Rust desktop applications. It combines a GPUI-style fluent view API, Taffy Flexbox, CSS Grid and parent-size container queries, WGPU rendering, retained Unicode text, native accessibility, and bounded virtual scrolling.

The current focus is production-quality macOS behavior with low idle CPU and bounded memory. Windows and Linux compile through Winit/WGPU but still need native runtime and visual acceptance.

## Performance model

- Clean windows sleep in `ControlFlow::Wait` and render no idle frames.
- Ordinary wheel scrolling and redraw requests coalesce at the event-loop boundary; opt-in
  element listeners preserve each native delta kind and gesture phase.
- Hover, scrolling, drag previews, and selection reuse retained layout where possible.
- Web-style hover, active, focus, validation, and drag transitions repaint retained geometry
  without rebuilding the view or rerunning layout.
- Element opacity multiplies through complete GPU/native subtrees, remains hit-testable at zero,
  and changes rich-text glyph alpha without invalidating shaping.
- Uniform and measured variable-height lists mount only visible rows and preserve logical anchors.
- Layout-isolated container queries redeclare only when their assigned parent size changes.
- Text, images, SVGs, paths, shaders, and GPU buffers use explicit retention bounds.
- Font families, OpenType features, and ordered application fallbacks inherit through ordinary and
  rich text while remaining part of canonical retained shaping keys.
- Compatible windows share the expensive WGPU instance, adapter, device, and queue.
- Native services, delayed UI, animation, and background completion wake only on events or exact deadlines.
- Native cursor declarations reuse retained hit testing and add no redraw or idle scheduling source.
- Raw touch contacts are captured per identity with a fixed per-window bound and no recognizer,
  monitor, polling task, or idle scheduling source.

## View API

Views are ordinary Rust with JSX-like composition and Tailwind-style helpers:

```rust
use quickgui::{App, Color, EventContext, IntoElement, View, ViewContext, div, text};

struct Counter {
    count: usize,
}

impl View for Counter {
    fn render(&mut self, cx: &mut ViewContext<'_, Self>) -> impl IntoElement {
        let increment = cx.listener("increment", |this, cx: &mut EventContext| {
            this.count += 1;
            cx.invalidate();
        });

        div()
            .size_full()
            .flex_col()
            .items_center()
            .justify_center()
            .gap_3()
            .bg(Color::rgb8(18, 18, 20))
            .text_color(Color::rgb8(240, 241, 244))
            .child(text(format!("Count: {}", self.count)).text_2xl())
            .child(
                div()
                    .on_click(increment)
                    .px_4()
                    .py_2()
                    .rounded_lg()
                    .bg(Color::rgb8(45, 105, 180))
                    .opacity(0.9)
                    .hover(|style| {
                        style.bg(Color::rgb8(56, 122, 204)).opacity(1.0)
                    })
                    .child("Increment"),
            )
    }
}

fn main() -> Result<(), quickgui::AppError> {
    App::new(Counter { count: 0 })
        .title("Counter")
        .size(480.0, 320.0)
        .run()
}
```

## Documentation

Start at the [documentation index](docs/README.md).

- [View API and layout]docs/view-api.md
- [Windows and shared state]docs/windows.md
- [Native document windows]docs/document-windows.md
- [Displays and window placement]docs/displays.md
- [macOS integration]docs/macos.md
- [Text, editing, and forms]docs/text-and-forms.md
- [Selection controls]docs/selection-controls.md
- [Tabs]docs/tabs.md
- [Popovers and popup menus]docs/popovers.md
- [Select and autocomplete]docs/select-and-autocomplete.md
- [Dialogs]docs/dialogs.md
- [Unstyled component roadmap]docs/component-roadmap.md
- [Virtual tables and trees]docs/data-collections.md
- [Application assets and custom fonts]docs/assets-and-fonts.md
- [Clipboard]docs/clipboard.md
- [Graphics and media]docs/graphics.md
- [Declarative motion]docs/animations.md
- [Input and interaction]docs/input.md
- [Asynchronous work]docs/async.md
- [Deterministic testing]docs/testing.md
- [Retained-tree inspector]docs/inspector.md
- [Examples and performance checks]docs/examples-and-performance.md
- [Releasing QuickGUI 0.1]docs/releasing.md
- [Changelog]CHANGELOG.md
- [Status and roadmap]docs/status.md
- [Architecture]docs/architecture/README.md

## Try it

```console
cargo run --release --example gesture_input
cargo run --release --example cursors
cargo run --release --example appearance
cargo run --release --example window_background
cargo run --release --example clipboard
cargo run --release --example assets
cargo run --release --example styled_text
cargo run --release --example selection_controls
cargo run --release --example tabs
cargo run --release --example popovers
cargo run --release --example anchored_popup
cargo run --release --example comboboxes
cargo run --release --example autocomplete
cargo run --release --example dialogs
cargo run --release --example data_collections
cargo run --release --example displays
cargo run --release --example animations
cargo run --features inspector --example inspector
cargo run --release --example stress_scroll
cargo run --example hacker_news
```

The stress example mounts only the visible slice of a 100,000-row list and includes live CPU/render
telemetry. On macOS, `scripts/macos-performance-gate.sh` gates bidirectional scrolling and
`scripts/macos-acceptance-gate.sh` gates native resize, wrapped and ellipsized text, embedded
`NSView` lifecycle, context-menu interaction and a 128-cycle popup memory plateau, idle behavior,
whole-process CPU, peak RSS, and process-owned graphics footprint against a real WindowServer. The
scripted popups are lifecycle evidence, not a human-visible visual recording.
`scripts/macos-display-acceptance-gate.sh` separately opens hidden, non-key windows on every active
display and requires exact first-render centering plus settled retained/AppKit screen identity,
scale, native-frame origin, work-area agreement, and full native-frame containment. Its report
marks unavailable mixed-scale hardware as skipped, never passed.

## Validate

```console
cargo test --all-targets --all-features --locked
cargo +1.89.0 check --all-targets --all-features --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo bench --bench virtual_list
cargo bench --bench animation
scripts/macos-performance-gate.sh
scripts/macos-acceptance-gate.sh
scripts/macos-display-acceptance-gate.sh
QUICKGUI_PACKAGE_TOOLCHAIN=1.89.0 scripts/package-release-gate.sh
```

## License

MIT OR Apache-2.0.