docs: redesign GUI around A3S Graphics

Author: Roy Lin

README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <em>Reducer-driven Rust components, structured RSX, and direct AppKit, GTK4, and WinUI rendering without a browser runtime.</em>
+  <em>Reducer-driven Rust components, structured RSX, and an A3S-owned GPU rendering engine without a browser runtime.</em>
 </p>
 
 ---
@@ -14,21 +14,23 @@
 
 **A3S GUI** is a native GUI runtime for structured A3S UI frames. Applications
 describe semantic UI in Rust function components or `.rsx` modules, update
-state through reducers, and render the same portable native IR through one of
-four hosts:
+state through reducers, and lower the same portable native IR into layout,
+paint, interaction, and accessibility records. Application pixels are moving
+to the shared [`a3s-graphics`](https://github.com/A3S-Lab/Graphics) engine,
+whose production path uses `wgpu` directly for Metal, Direct3D 12, and Vulkan.
 
-- AppKit on macOS
-- GTK4 on Linux
-- WinUI on Windows
-- a deterministic headless host for tests and protocol integration
+The current AppKit, GTK4, WinUI, and deterministic headless hosts remain as the
+migration baseline. New rendering work targets the self-drawn Graphics path;
+the three control renderers will be removed after the generic calculator,
+input, IME, and accessibility cutover gates pass.
 
 The crate provides:
 
 - `ComponentCx` function components with state, props, context, derived values,
   effects, resources, reducers, and interaction hooks
 - static RSX lowering for semantic components, intrinsic elements, bindings,
   actions, fragments, slots, and spreads
-- keyed reconciliation and ordered native command batches
+- stable semantic identity, retained rendering, and ordered frame transactions
 - a strict versioned protocol with prepare, commit, ACK, recovery, replay, and
   sensitive-value redaction
 - portable interaction behavior for press, hover, focus, selection, overlays,
@@ -40,9 +42,10 @@ The crate provides:
 - a built-in `rsx_ui` component registry plus calculator, dogfood, and
   component-playground applications
 
-A3S GUI does not embed a DOM, CSSOM, WebView, or JavaScript object graph. RSX
-uses familiar component syntax, but it compiles into typed native data and
-platform widget operations.
+A3S GUI does not embed a DOM, CSSOM, WebView, framework-owned content renderer,
+or JavaScript object graph.
+RSX uses familiar component syntax, but it compiles into typed semantic,
+layout, graphics-scene, interaction, and accessibility data.
 
 The long-term behavioral direction is a native, cross-platform counterpart to
 [React Aria](https://react-aria.adobe.com/getting-started). This is not a DOM
@@ -60,8 +63,8 @@ a3s-gui = { git = "https://github.com/A3S-Lab/GUI" }
 ```
 
 The default feature set includes the headless runtime, RSX authoring, and the
-built-in design system. Add the matching native feature to open real platform
-widgets:
+built-in design system. During the renderer migration, the matching legacy
+native feature still opens the platform-control baseline:
 
 ```toml
 # macOS
@@ -125,10 +128,10 @@ just playground
 | `headless` | Deterministic runtime and host behavior without an OS GUI |
 | `authoring` | SWC-backed RSX parsing, `ComponentCx`, and explicit component registries |
 | `design-system` | Built-in `rsx_ui` registry; implies `authoring` |
-| `appkit`, `gtk4`, `winui` | Pure planning adapters that do not link an OS widget toolkit |
-| `appkit-native` | Real AppKit surface on macOS |
-| `gtk4-native` | Real GTK4 surface on Linux |
-| `winui-native` | Real WinUI 3 surface on Windows |
+| `appkit`, `gtk4`, `winui` | Legacy planning adapters retained for migration evidence |
+| `appkit-native` | Legacy AppKit control surface on macOS |
+| `gtk4-native` | Legacy GTK4 control surface on Linux |
+| `winui-native` | Legacy WinUI 3 control surface on Windows |
 
 Runtime and protocol consumers can exclude the authoring stack:
 
@@ -150,15 +153,23 @@ Rust ComponentCx function or .rsx module
                     |
                     v
         semantic native UI IR
+          /         |          \
+         v          v           v
+      layout    semantics   interaction/hit tree
+         |          |           |
+         v          |           |
+   Graphics Scene   |           |
+         |          |           |
+         v          |           |
+ software / wgpu    |           |
+         |          |           |
+         +----------+-----------+
                     |
                     v
- keyed reconciliation and command batches
+    thin platform host and normalized events
                     |
                     v
- AppKit / GTK4 / WinUI / headless host
-                    |
-                    v
- normalized native events and action reducers
+              action reducers
 ```
 
 The main ownership boundaries are explicit:
@@ -168,13 +179,13 @@ The main ownership boundaries are explicit:
 | Authoring | Rust components, hooks, RSX parsing, component contracts, and bindings |
 | Protocol | Serializable frames, actions, revisions, events, ACKs, and recovery |
 | Runtime | Reducer flow, interaction state, effects, focus, selection, and overlays |
-| Renderer | Stable-key reconciliation and ordered host operations |
-| Platform planning | Portable widget blueprints, setters, capabilities, and command batches |
-| Native surface | OS widget lifetime, thread affinity, raw input, focus, accessibility, and event delivery |
+| Layout and scene adapter | Stable layout records, paint extraction, hit regions, and explicit projection diagnostics |
+| A3S Graphics | Scene validation, retained damage, render preparation, software reference, shaders, and GPU rendering |
+| Platform host | Window/surface lifetime, raw input, IME, focus, accessibility bridge, system surfaces, and event delivery |
 
-Application state and product I/O remain outside the renderer. Native backends
-never execute component functions, and thread-affine native handles never cross
-the serializable host boundary.
+Application state and product I/O remain outside the renderer. Graphics and
+platform hosts never execute component functions, and thread-affine native or
+GPU handles never cross the serializable boundary.
 
 ## Component And Hook Model
 
@@ -272,7 +283,8 @@ framework.
 | Headless runtime | Usable for deterministic tests, protocol sessions, rendering, accessibility, and capability inspection |
 | Protocol and native execution | Versioned protocol v1 with ordered revisions, retained resend, exact ACK validation, degraded state, and fresh-executor replay |
 | Built-in design system | Broad dogfood component set with calculator and component-atlas coverage |
-| AppKit, GTK4, and WinUI | Real native surfaces with host-native CI; continuing platform-edge hardening |
+| Self-drawn Graphics path | Deterministic scene/reference core exists independently; GPU and GUI lowering are the active P0 work |
+| AppKit, GTK4, and WinUI controls | Migration baseline only; frozen until removal after self-drawn cutover |
 | Native input evidence | Canonical manifests and a strict verifier are implemented; the WinUI harness covers its current 98-case matrix, while AppKit and GTK4 OS-automation evidence is incomplete |
 | Packaging | Reproducible unsigned smoke bundles; signing, notarization, installers, and product update metadata remain application responsibilities |
 | React Aria direction | Substantial shared behavior foundation; full component, platform, and assistive-technology parity is still in progress |
@@ -301,7 +313,7 @@ just playground
 just dogfood-native
 ```
 
-The AppKit, GTK4, and WinUI calculator entrypoints use the same
+The legacy AppKit, GTK4, and WinUI calculator entrypoints use the same
 `shared_calculator_component`, state model, reducer, RSX component tree, window
 constraints, and explicit keypad sizing. Their semantics and layout intent are
 therefore shared. Exact pixels still follow each native toolkit's control
@@ -323,8 +335,9 @@ cargo run --locked --features <backend>-native --example <backend>_dogfood
 | --- | --- |
 | Authoring | Rust-first function components and static RSX, not JavaScript execution |
 | State | Explicit reducers and one-way state-to-frame-to-action flow |
-| Rendering | Semantic native IR and stable-key reconciliation |
-| Widgets | Real AppKit, GTK4, and WinUI controls by default |
+| Rendering | Native IR to deterministic GUI layout and A3S Graphics scene |
+| Pixels | A3S-owned software reference and `wgpu` renderer; no framework-owned content renderer |
+| Platform | Thin window, input, IME, accessibility, system-surface, and presentation hosts |
 | Behavior | Shared headless contracts with field- and role-level native capability reporting |
 | Accessibility | Portable semantic truth plus exact native projection where supported |
 | Styling | Portable native style tokens and selected utility syntax, not a browser CSS engine |
@@ -338,17 +351,17 @@ cargo run --locked --features <backend>-native --example <backend>_dogfood
 src/
 ├── accessibility/    # Semantic tree, conformance, relationships, and native-ready values
 ├── app/              # Reducer-driven native application loop
-├── backend/          # Command execution, recording, and recovery
-├── platform/         # Portable widget planning and setter batches
+├── backend/          # Legacy command execution and recovery during migration
+├── platform/         # Legacy widget planning during migration
 ├── protocol.rs       # Versioned frame, action, event, and ACK boundary
 ├── native.rs         # Portable native UI IR
-├── renderer.rs       # Stable-key reconciliation
+├── renderer.rs       # Legacy stable-key control reconciliation
 ├── runtime/          # Interaction, focus, overlays, effects, and rerender flow
 ├── rsx_app/          # ComponentCx, hooks, components, and binding scope
 ├── rsx_ui/           # Built-in semantic design-system registry
-├── appkit_native/    # Real macOS surface
-├── gtk4_native/      # Real Linux surface
-└── winui_native/     # Real Windows surface
+├── appkit_native/    # Legacy macOS control surface; future thin host
+├── gtk4_native/      # Legacy Linux control surface; future thin host
+└── winui_native/     # Legacy Windows control surface; future thin host
 
 examples/             # Headless, calculator, dogfood, controls, and playground apps
 docs/                 # Architecture, language, platform, packaging, and roadmap contracts

docs/architecture.md

@@ -1,13 +1,24 @@
 # a3s-gui Architecture
 
-`a3s-gui` accepts structured UI input and emits native platform commands for
-AppKit, WinUI, and GTK4 backends.
+`a3s-gui` accepts structured UI input and produces a deterministic layout,
+paint scene, interaction tree, and accessibility tree. Application content is
+rendered by the A3S-owned [`a3s-graphics`](https://github.com/A3S-Lab/Graphics)
+engine. Graphics uses a deterministic software reference path and an owned
+`wgpu` path for Metal, Direct3D 12, and Vulkan; it has no RSX, widget,
+accessibility, or window-system dependency.
 
 The input contract is structured RSX element data: protocol element records,
 semantic element names, `className`, inline style objects, `aria-*`, `data-*`,
 and DOM-style event props. Supported `semantic_ui` component names are treated
-as semantic identifiers. The renderer consumes A3S Native UI IR; host adapters
-create platform widgets directly.
+as semantic identifiers. The renderer consumes A3S Native UI IR. Thin platform
+hosts own windows, raw input, IME, accessibility bridges, menus, dialogs,
+clipboard, and frame presentation, but they do not lay out or draw application
+content.
+
+The current AppKit, GTK4, and WinUI control renderers remain a migration
+baseline until the self-drawn calculator passes the cross-platform cutover
+gates. They are compatibility code, not the target architecture. New rendering
+features must enter through the layout and Graphics scene path.
 
 ```text
 Rust ComponentCx function + optional RSX view template
@@ -29,21 +40,30 @@ Semantic UI tree
         |
         v
 A3S Native UI IR
+   /         |          \
+  v          v           v
+layout   semantics   interaction/hit tree
+  |          |           |
+  v          |           |
+A3S Graphics Scene       |
+  |          |           |
+  v          |           |
+FramePlanner |           |
+  |          |           |
+  +----+     |           |
+       |     |           |
+       v     |           |
+software / wgpu renderer |
+       |     |           |
+       v     v           |
+thin platform host <-----+
+  - window + surface presentation
+  - raw input + IME
+  - accessibility bridge
+  - menus, dialogs, clipboard
         |
         v
-Keyed renderer diff engine
-        |
-        v
-Native command stream
-        |
-        v
-NativeHost adapter
-  - AppKit on macOS
-  - WinUI on Windows
-  - GTK4 on Linux
-        |
-        v
-Native events
+Normalized native events
         |
         v
 HostEvent protocol
@@ -61,8 +81,8 @@ Action ids
 ## Contract
 
 The bridge accepts semantic component names, HTML and SVG intrinsic names,
-common Web props, and event names. The native renderer receives a typed,
-portable protocol. Input records come from Rust `ComponentCx` functions,
+common Web props, and event names. The GUI renderer receives a typed, portable
+protocol. Input records come from Rust `ComponentCx` functions,
 registered `.rsx` view templates, `RsxComponent` hook registrations, or Rust
 code that builds the same protocol shape.
 
@@ -132,17 +152,23 @@ semantic mapper, renderer, and planning core compile without SWC or `rsx_ui`.
 The remaining dependencies stay one-way:
 
 - `ComponentCx`, RSX parsing, and `rsx_ui` authoring compile outward-facing
-  syntax into `CompiledRsxNode`; native backends never execute component
-  functions.
+  syntax into `CompiledRsxNode`; layout, Graphics, and platform hosts never
+  execute component functions.
 - `rsx_ui` depends on semantic component contracts. The semantic mapper,
-  native IR, renderer, and platform planning layers do not depend on the
+  native IR, layout, scene adapter, and Graphics layers do not depend on the
   built-in design-system registry.
-- `src/native.rs`, reconciliation, and `src/platform/` remain independent of OS
-  widget handles. AppKit, GTK4, and WinUI surfaces depend on those portable
-  types and are selected behind their target/feature boundaries.
-- `src/backend/` executes planned commands but does not own product state or
-  product I/O. The serializable host boundary carries data and command records,
-  never component runtime instances or thread-affine native handles.
+- GUI layout and scene extraction depend on `a3s-graphics` public scene types.
+  `a3s-graphics` never depends on `a3s-gui`, an operating-system window API, or
+  product code.
+- `wgpu` types remain inside Graphics. They do not leak into protocol,
+  `NativeElement`, portable style, components, or product application APIs.
+- Platform hosts consume GUI interaction/accessibility records and Graphics
+  presentation records. Thread-affine window, accessibility, IME, and surface
+  handles stay at that outer edge.
+- During migration, `src/renderer.rs`, `src/host.rs`, `src/platform/`, and
+  `src/backend/` implement the legacy control path. They may not gain new
+  visual behavior and are deleted when the equivalent scene/presentation and
+  recovery gates pass.
 - `src/effect.rs` defines an executor seam without depending on Tokio or another
   application runtime. An application may inject such an executor at the outer
   edge.
@@ -195,7 +221,11 @@ artifact. The harness requires an interactive Windows desktop and the Windows
 App Runtime 1.7 framework package used by the WinUI backend's dynamic
 dependency.
 
-## NativeHost Boundary
+## Legacy NativeHost Compatibility Boundary
+
+This section documents the current control renderer so its behavior can be
+preserved and then removed deliberately. It is not the destination for new
+rendering work. The removal gates are tracked in `docs/roadmap.md`.
 
 Every platform adapter implements the same host operations:
 

docs/react-aria-native.md

@@ -7,8 +7,8 @@ design system without depending on a browser.
 
 This is a behavioral compatibility target, not a DOM compatibility target.
 React Aria's public concepts should have recognizable native equivalents, but
-the implementation must use AppKit, GTK4, and WinUI controls, focus systems,
-accessibility APIs, and input events directly.
+the implementation uses A3S-owned layout and Graphics rendering together with
+the operating system's window, focus, accessibility, IME, and input APIs.
 
 The project does not claim React Aria parity yet.
 
@@ -25,13 +25,20 @@ Headless behavior contracts
 Portable semantic tree and typed Native UI IR
                 |
                 v
-Behavior state machines and keyed reconciliation
+GUI layout, behavior state machines, and stable identity
                 |
-                v
-Versioned platform capabilities
+       +--------+--------+
+       |                 |
+       v                 v
+A3S Graphics scene   semantic/accessibility tree
+       |                 |
+       v                 v
+software / wgpu     platform accessibility bridge
+       |                 |
+       +--------+--------+
                 |
                 v
-AppKit / GTK4 / WinUI native adapters
+thin macOS / Linux / Windows host
 
 Native input and accessibility events travel upward through the same layers.
 ```