feat: add atomic self-drawn runtime and React Aria gate

Author: Roy Lin

Cargo.toml

@@ -27,6 +27,10 @@ required-features = ["winui-native"]
 name = "component_playground"
 required-features = ["authoring"]
 
+[[example]]
+name = "self_drawn_calculator"
+required-features = ["authoring", "platform-runtime", "software-reference"]
+
 [[example]]
 name = "appkit_counter"
 required-features = ["appkit-native"]
@@ -94,6 +98,7 @@ graphics = ["dep:a3s-graphics"]
 software-reference = ["graphics", "a3s-graphics/software"]
 gpu = ["graphics", "a3s-graphics/gpu"]
 platform-host = []
+platform-runtime = ["platform-host", "graphics"]
 host-macos = ["platform-host"]
 host-windows = ["platform-host"]
 host-linux-wayland = ["platform-host"]

README.md

@@ -21,7 +21,8 @@ path uses a DOM, CSSOM, WebView, or framework-owned content renderer.
 > generic self-drawn layout-to-Scene slice has landed; self-drawn text, input,
 > IME, accessibility bridges, and real thin-host presentation remain roadmap
 > work. The TSX runtime, local host session, and npm packages are architecture
-> only and have not been implemented yet.
+> only and have not been implemented yet. React Aria component parity is not
+> claimed yet.
 
 The target is unambiguous: A3S draws all application content. The existing
 `appkit-native`, `gtk4-native`, and `winui-native` modules create controls only
@@ -55,6 +56,29 @@ The GPU result is local DX12 evidence, not a Metal/Vulkan parity claim. Text and
 real self-drawn window presentation are not represented by the screenshot
 above.
 
+## Complete React Aria scope
+
+The calculator is only the first vertical renderer fixture. The product target
+remains every semantic component in the official React Aria catalog. The
+versioned [component matrix](docs/react-aria-component-matrix.json) pins
+`react-aria-components` 1.19.0 and is schema-checked in CI:
+
+- all 51 official top-level component families map to registered A3S RSX
+  authoring components;
+- `Button` currently has scene/software-pixel smoke evidence through the shared
+  calculator, but no component is self-drawn conformant yet;
+- Checkbox, Radio, and Switch Field/Button parts plus ToastList and
+  ToastContent are recorded as eight explicit API gaps;
+- a component reaches `conformant` only with behavior, layout/hit, Graphics
+  scene, deterministic software, accessibility, and real self-drawn macOS,
+  Windows, and Linux evidence.
+
+Existing AppKit, GTK4, and WinUI control paths cannot satisfy that final gate.
+They remain frozen comparison baselines until the equivalent A3S-drawn stories
+pass and their content-control code is removed. See the
+[React Aria native direction](docs/react-aria-native.md) for the acceptance
+contract.
+
 ## TSX to native, without a browser
 
 The proposed TypeScript path follows
@@ -218,8 +242,10 @@ independently.
   bindings, fragments, slots, and spreads
 - stable semantic identity and ordered prepare/commit/ACK transactions with
   rollback, degraded-state recovery, replay, and sensitive-value redaction
-- a broad built-in `rsx_ui` registry covering foundations, forms, collections,
-  overlays, date/time, color, feedback, routing, and drag/drop semantics
+- a broad built-in `rsx_ui` registry with name-level coverage for all 51 pinned
+  React Aria families across foundations, forms, collections, overlays,
+  date/time, color, feedback, routing, and drag/drop semantics; this is
+  authoring coverage, not a self-drawn parity claim
 
 ### Interaction and accessibility
 
@@ -259,6 +285,20 @@ independently.
 - executable source and Cargo-feature firewalls proving the common contract has
   no Graphics, OS toolkit, or legacy renderer dependency
 
+### Atomic self-drawn frames
+
+- opt-in `platform-runtime` orchestration from one owned `NativeElement` tree
+  through layout, hit regions, Graphics Scene, accessibility, and a monotonic
+  zero-widget host transaction
+- a transactional `PlatformScenePresenter` seam: pixels are prepared without
+  exposure, published only after host commit, and discarded on rejection
+- retained resize, fractional-scale, damage, occlusion, redraw, delayed
+  acknowledgement, and surface-loss replay without changing semantic identity
+- an identical-frame fast path that performs no layout, scene, host, or
+  presentation work, plus semantic-only commits that skip pixel presentation
+- a software Graphics presenter and shared `self_drawn_calculator` smoke that
+  preserve the reviewed 410x620 layout and scene fingerprints
+
 ## Roadmap at a glance
 
 | Milestone | State | Evidence or next gate |
@@ -269,8 +309,9 @@ independently.
 | M3 · Layout and Scene | Current | Generic calculator rectangle slice landed; full flex, stacking, redraw scheduling, cross-platform fingerprints, and thin-host presentation remain |
 | M4 · Text and interaction cutover | Planned | Shaping, glyphs, GUI-owned input, IME, accessibility bridges, overlays, and complete calculator scenarios |
 | M5 · Default cutover | Planned | Make self-drawn content the default, then delete the three legacy widget renderers |
-| H0-H5 · Thin platform hosts | H0 complete; H1 next | Zero-widget records, transactions, recording host, target feature markers, and dependency/source firewalls landed; shared window runtime is next |
+| H0-H5 · Thin platform hosts | H0 complete; H1 in progress | Atomic shared frames, transactional presentation, lifecycle recovery, zero-toolkit firewalls, and calculator pixels landed; portable input/reducer routing and a real raw-surface presenter remain |
 | T0-T5 · TSX native authoring | Proposed | Automatic JSX runtime, versioned Node-to-host session, state/event runtime, self-drawn native window, packages, and stable SDK |
+| M6-M8 · React Aria components | Catalog pinned; conformance planned | 51/51 families mapped, eight public parts explicitly missing, Button scene smoke only; full software and three-OS self-drawn evidence required |
 
 The dependency-ordered plan and acceptance gates are in the
 [delivery roadmap](docs/roadmap.md).
@@ -286,6 +327,7 @@ The default set is `headless + authoring + design-system + software-reference`.
 | `software-reference` | Deterministic retained reference renderer; implies `graphics` |
 | `gpu` | Owned offscreen GPU renderer and readback path; implies `graphics` |
 | `platform-host` | H0 zero-widget records, transaction trait, recording host, and conformance tests; no Graphics or OS dependency |
+| `platform-runtime` | H1 Native IR/layout/scene/accessibility frame orchestration over `platform-host + graphics`; no OS toolkit dependency |
 | `host-macos`, `host-windows` | H0 target markers over `platform-host`; OS shell implementations land in H2/H3 |
 | `host-linux-wayland`, `host-linux-x11`, `host-linux` | H0 target markers over `platform-host`; Linux implementations land in H4 |
 | `authoring` | SWC-backed RSX parsing, `ComponentCx`, and explicit component registries |
@@ -305,6 +347,9 @@ cargo check --locked --no-default-features --features software-reference --lib
 cargo check --locked --no-default-features --features gpu --lib
 cargo check --locked --no-default-features --features platform-host --lib
 cargo test --locked --no-default-features --features platform-host --lib platform_host::
+cargo check --locked --no-default-features --features platform-runtime --lib
+cargo test --locked --no-default-features --features platform-runtime --lib platform_runtime::
+cargo test --locked --test react_aria_component_matrix
 ```
 
 ## Platform hosts: migration baseline and target
@@ -350,6 +395,7 @@ cargo run --locked --example state_loop
 cargo run --locked --example native_runtime_app
 cargo run --locked --example dogfood_session
 cargo run --locked --example component_playground
+cargo run --locked --no-default-features --features authoring,platform-runtime,software-reference --example self_drawn_calculator
 ```
 
 Host-selecting recipes:
@@ -415,10 +461,11 @@ src/
 |                        LayoutSnapshot to Graphics Scene lowering
 |- render_contract.rs    executable field/role/event milestone inventory
 |- platform_host/        H0 zero-widget records, transactions, recorder, and validation
+|- platform_runtime/     H1 atomic frames, presentation lifecycle, and Graphics smoke
 |- backend/ + platform/  legacy execution/planning migration baseline
 `- *_native/             AppKit, GTK4, and WinUI control hosts during migration
 
-examples/                headless, calculator, dogfood, controls, and playground apps
+examples/                headless, self-drawn, calculator, dogfood, controls, and playground apps
 docs/                    architecture, contracts, packaging, language, and roadmap
 packaging/               unsigned native smoke-bundle assets and validators
 ```
@@ -436,6 +483,7 @@ packaging/               unsigned native smoke-bundle assets and validators
 - [TSX to native runtime architecture](docs/tsx-native-runtime.md)
 - [Native style contract](docs/style-contract.md)
 - [React Aria native direction](docs/react-aria-native.md)
+- [Executable React Aria component matrix](docs/react-aria-component-matrix.json)
 - [Native app shell](docs/app-shell.md)
 - [Native packaging](docs/packaging.md)
 - [Delivery roadmap](docs/roadmap.md)

docs/architecture.md

@@ -140,6 +140,24 @@ This is a runtime ownership boundary, not a second component model. All three
 paths produce the same compiled RSX tree and enter the same semantic/native
 lowering pipeline.
 
+### React Aria catalog gate
+
+The built-in registry is checked against the complete official React Aria
+Components 1.19.0 navigation catalog. The versioned
+[`react-aria-component-matrix.json`](react-aria-component-matrix.json) contains
+all 51 top-level families, their registered A3S component parts, the eight
+currently missing public parts, delivery milestones, self-drawn status, and
+evidence links. `tests/react_aria_component_matrix.rs` rejects a missing family,
+an unregistered mapping, an untracked newly implemented part, or a conformance
+claim without software and all three operating-system lanes.
+
+Registry coverage proves that an author can name and lower a component. It
+does not prove self-drawn parity. Component completion additionally requires
+portable behavior, layout and hit regions, Graphics scene and deterministic
+pixels, accessibility semantics, and real self-drawn macOS/Windows/Linux host
+automation. AppKit, GTK4, and WinUI content-control runs remain migration
+oracles only.
+
 ## Dependency Direction
 
 Cargo features enforce both the authoring/runtime split and the graphics
@@ -149,8 +167,11 @@ the built-in `rsx_ui` registry. `graphics` enables only the pinned engine scene
 contract, while `software-reference` adds deterministic retained
 rasterization. `gpu` adds the real offscreen renderer, capability report, and
 readback path from pinned Graphics commit `8748fab`; there is no placeholder
-backend. The default feature set keeps the existing authoring experience plus
-software reference evidence, while
+backend. `platform-host` adds only bounded zero-widget OS records, while
+`platform-runtime` adds the one-way Native IR/layout/scene/accessibility frame
+coordinator and Graphics presentation seam without enabling an OS toolkit. The
+default feature set keeps the existing authoring experience plus software
+reference evidence, while
 `cargo check --no-default-features --lib` proves that protocol, semantic,
 interaction, focus, selection, i18n, and accessibility remain usable without
 Graphics, SWC, or `rsx_ui`.
@@ -168,9 +189,13 @@ diagnostics share those identities. The semantic-only layout module produces a
 versioned `LayoutSnapshot`, while the optional Graphics adapter rejects
 error-level M3 omissions and derives stable `DrawId` values from layout paths.
 The existing shared calculator tree pins layout and scene fingerprints plus
-software and local Direct3D 12 image evidence. This is rectangle-path evidence,
-not a claim that text, full flex/grid behavior, presentation, or M4 interaction
-has landed.
+software and local Direct3D 12 image evidence. The H1-in-progress
+`SelfDrawnWindowRuntime` now commits that same tree, layout, hit data, scene,
+and accessibility projection as one monotonic host frame. Its transactional
+presenter publishes software Graphics pixels only after host commit and replays
+the last scene after surface loss. This remains rectangle-path evidence, not a
+claim that text, full flex/grid behavior, a real OS swapchain, or portable M4
+input routing has landed.
 
 The remaining dependencies stay one-way:
 
@@ -205,6 +230,11 @@ capability types but must not depend on the ACL parser or its AST.
 
 ## Native Input Evidence Boundary
 
+The existing capability manifests in this section describe the legacy
+content-control baseline that the self-drawn runtime must preserve. They do not
+complete a React Aria matrix entry. Final component evidence must drive the
+zero-widget platform hosts and A3S-owned pixels.
+
 `NativeCapabilities` describes the behavior a backend claims for each role.
 `NativeInputConformanceManifestV1` turns native press claims into a canonical
 role/scenario matrix, including activation, cancellation, disabled-state, and

docs/platform-hosts.md

@@ -1,9 +1,10 @@
 # Self-Drawn Platform Host Architecture
 
-Status: H0 contract and dependency firewall complete; H1 shared window runtime
-is next. The desktop OS shells described here are not implemented yet.
+Status: H0 complete; H1 atomic frame orchestration and presentation lifecycle
+in progress. Portable input/reducer routing and real desktop OS shells are not
+implemented yet.
 
-Updated: 2026-08-01
+Updated: 2026-08-02
 
 ## Decision
 
@@ -43,12 +44,15 @@ The repository currently contains three distinct layers:
    system-service records; atomic revision transactions; a recording host; and
    executable dependency/source firewalls.
 
-The next missing layer is the H1 shared runtime that connects committed layout,
-scene, hit-region, accessibility, and service state to the new host contract.
-Production H2-H4 hosts must then attach Graphics to real top-level surfaces and
-return OS services without constructing content controls. The old control
-backends are frozen until this replacement passes its gates. They are migration
-inputs, not the target architecture and not a base for new TSX work.
+The first H1 layer now connects committed Native IR, layout, scene, hit-region,
+and accessibility state to the new host contract. It also owns transactional
+scene preparation/publication plus resize, scale, damage, occlusion, redraw,
+delayed acknowledgement, and surface-loss replay. Portable hit/focus/action
+routing is the next H1 slice. Production H2-H4 hosts must then attach Graphics
+to real top-level surfaces and return OS services without constructing content
+controls. The old control backends are frozen until this replacement passes
+its gates. They are migration inputs, not the target architecture and not a
+base for new TSX work.
 
 ## Target Pipeline
 
@@ -200,21 +204,35 @@ src/platform_host/
 
 tests/platform_host_firewall.rs
 
+src/platform_runtime/
+|- frame.rs             committed Native IR/layout/scene/a11y snapshot
+|- runtime.rs           atomic candidate preparation and host commit
+|- events.rs            resize, scale, occlusion, redraw, and ack lifecycle
+|- presenter.rs         raw-surface prepare/publish contract and recorder
+|- reference_presenter.rs
+|                       transactional software Graphics evidence
+|- accessibility.rs     stable layout-path semantic projection
+`- tests.rs             atomicity, no-op, recovery, and identity gates
+
+tests/platform_runtime_firewall.rs
+examples/self_drawn_calculator.rs
+
 Planned next:
-src/platform_host/runtime.rs
+src/platform_runtime/interaction.rs
 src/platform_host/macos/
 src/platform_host/windows/
 src/platform_host/linux/
 
-examples/self_drawn_calculator.rs
 src/bin/a3s_gui_host.rs
 ```
 
 The `platform-host`, `host-macos`, `host-windows`, `host-linux-wayland`,
-`host-linux-x11`, and `host-linux` features landed in H0. The target features
-currently select the common contract only; OS dependencies arrive with their
-H2-H4 implementation. None enables or imports `appkit-native`, `gtk4-native`,
-`winui-native`, or the legacy widget-planning modules.
+`host-linux-x11`, and `host-linux` features landed in H0. H1 adds the separate
+`platform-runtime = platform-host + graphics` feature so the H0 wire boundary
+stays Graphics-free. The target features currently select the common contract
+only; OS dependencies arrive with their H2-H4 implementation. Neither H0 nor
+H1 enables or imports `appkit-native`, `gtk4-native`, `winui-native`, or the
+legacy widget-planning modules.
 
 The new modules are created beside the legacy directories rather than by
 renaming a control backend. This makes accidental content-widget reuse visible
@@ -307,7 +325,7 @@ Evidence:
 
 ### H1 - Shared self-drawn window runtime
 
-Status: next; depends on the M3 presentation boundary.
+Status: in progress; atomic frame and presentation-lifecycle slice landed.
 
 Deliverables:
 
@@ -319,6 +337,30 @@ Deliverables:
   pipeline
 - add the shared `self_drawn_calculator` entrypoint and fake-host smoke runner
 
+Landed evidence:
+
+- `SelfDrawnWindowRuntime` builds one immutable Native IR, layout, hit-region,
+  scene, and stable-id accessibility snapshot before host mutation
+- `PlatformScenePresenter` prepares candidate pixels, publishes only after a
+  matching host commit, and discards rejected candidates
+- identical frames skip layout, scene, host, and presenter work; semantic-only
+  changes commit accessibility without presenting identical pixels
+- resize, fractional scale, damage, occlusion, redraw, delayed acknowledgements,
+  dropped frames, and surface loss replay the retained scene deterministically
+- 14 focused runtime/software tests and three recursive feature/source
+  firewall tests pass without any legacy renderer or OS toolkit dependency
+- `self_drawn_calculator` commits the existing 410x620 shared Native IR and
+  reproduces layout fingerprint `16529597026056060935`, scene fingerprint
+  `2100550662756266801`, and deterministic RGBA pixels
+
+Remaining before H1 is complete:
+
+- route raw host input through portable hit testing, focus, interaction state,
+  action selection, and the application reducer without a legacy widget plan
+- implement the Graphics raw-surface presenter used by H2-H4; the landed
+  presenter contract and software implementation deliberately expose no raw
+  handle to components or common host records
+
 Gates:
 
 - an unchanged frame creates no new layout, scene, or present work
@@ -463,7 +505,8 @@ or dependency-boundary evidence.
 
 ## First Reviewable Commit Sequence
 
-1. Add H1 shared frame orchestration and raw-surface presentation lifecycle.
+1. Finish H1 portable hit/focus/reducer routing and bind its presenter contract
+   to the Graphics raw-surface edge.
 2. Present the rectangle-only shared calculator through the Windows host.
 3. Present the same rectangle-only calculator through the macOS host.
 4. Present it through Wayland, then add the separately gated X11 fallback.