feat: add zero-widget platform host contract

Author: Roy Lin

Cargo.toml

@@ -93,6 +93,12 @@ headless = []
 graphics = ["dep:a3s-graphics"]
 software-reference = ["graphics", "a3s-graphics/software"]
 gpu = ["graphics", "a3s-graphics/gpu"]
+platform-host = []
+host-macos = ["platform-host"]
+host-windows = ["platform-host"]
+host-linux-wayland = ["platform-host"]
+host-linux-x11 = ["platform-host"]
+host-linux = ["host-linux-wayland", "host-linux-x11"]
 authoring = [
     "dep:swc_atoms",
     "dep:swc_common",

README.md

@@ -245,6 +245,20 @@ independently.
 - deterministic retained software rendering and an owned `wgpu` renderer
   boundary with asynchronous readback
 
+### Zero-widget platform boundary
+
+- opt-in `platform-host` contracts for top-level windows, presentation,
+  un-targeted input, text/IME state, accessibility snapshots and actions,
+  explicit system services, and ordered host events
+- stable `PlatformElementId` accessibility identity independent from the
+  legacy control renderer and its `HostNodeId`
+- one bounded, validated revision transaction with prepare, atomic commit,
+  rollback, monotonic ordering, and explicit teardown semantics
+- a deterministic `RecordingPlatformHost` with bounded event/history storage,
+  commit-failure recovery, and sensitive diagnostic redaction
+- executable source and Cargo-feature firewalls proving the common contract has
+  no Graphics, OS toolkit, or legacy renderer dependency
+
 ## Roadmap at a glance
 
 | Milestone | State | Evidence or next gate |
@@ -255,7 +269,7 @@ 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 | Planned | Zero-widget host contract, shared window runtime, Win32/macOS/Wayland-X11 slices, and dependency-audited cutover |
+| 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 |
 | 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 |
 
 The dependency-ordered plan and acceptance gates are in the
@@ -271,6 +285,9 @@ The default set is `headless + authoring + design-system + software-reference`.
 | `graphics` | Pinned A3S Graphics scene vocabulary without a renderer backend |
 | `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 |
+| `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 |
 | `design-system` | Built-in `rsx_ui` registry; implies `authoring` |
 | `appkit`, `gtk4`, `winui` | Legacy planning adapters retained for migration evidence |
@@ -286,6 +303,8 @@ cargo check --locked --no-default-features --features authoring --lib
 cargo check --locked --no-default-features --features graphics --lib
 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::
 ```
 
 ## Platform hosts: migration baseline and target
@@ -395,7 +414,7 @@ src/
 |- drawing/layout_scene.rs
 |                        LayoutSnapshot to Graphics Scene lowering
 |- render_contract.rs    executable field/role/event milestone inventory
-|- platform_host/        planned zero-widget OS shell and presentation boundary
+|- platform_host/        H0 zero-widget records, transactions, recorder, and validation
 |- backend/ + platform/  legacy execution/planning migration baseline
 `- *_native/             AppKit, GTK4, and WinUI control hosts during migration
 

docs/platform-hosts.md

@@ -1,7 +1,7 @@
 # Self-Drawn Platform Host Architecture
 
-Status: planned. The all-content self-drawn direction is decided; the thin
-desktop hosts described here are not implemented yet.
+Status: H0 contract and dependency firewall complete; H1 shared window runtime
+is next. The desktop OS shells described here are not implemented yet.
 
 Updated: 2026-08-01
 
@@ -30,20 +30,25 @@ or layout container with a toolkit widget.
 
 ## Current State and Gap
 
-The repository currently contains two different generations of code:
+The repository currently contains three distinct layers:
 
 1. `appkit_native/`, `gtk4_native/`, and `winui_native/` create toolkit
    controls. They provide migration evidence for behavior, input,
    accessibility, packaging, and real OS execution.
 2. `layout/` and `drawing/layout_scene.rs` form the new generic self-drawn
    path. The calculator already lowers into stable layout and scene records,
    and the software and offscreen GPU renderers have executable evidence.
-
-The missing layer is a production window host that attaches the Graphics GPU
-renderer to a real top-level surface and returns OS services to the portable
-runtime 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.
+3. `platform_host/` is the H0 zero-widget boundary. It provides bounded window,
+   presentation, raw-input, text-input, stable-id accessibility, and explicit
+   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.
 
 ## Target Pipeline
 
@@ -178,32 +183,63 @@ a fake host and by all three desktop shells.
 - avoid exposing native handles or arbitrary platform calls to components or
   the TSX process
 
-## Planned Repository Shape
+## Repository Shape
 
 ```text
 src/platform_host/
-|- mod.rs
-|- contract.rs          window, frame, event, and service records
-|- runtime.rs           render/service transaction orchestration
-|- conformance.rs       shared fake-host and zero-widget assertions
-|- macos/               NSWindow + custom NSView shell
-|- windows/             Win32 HWND shell
-`- linux/               Wayland primary + X11 fallback shell
+|- mod.rs               public H0 boundary
+|- contract.rs          revision transaction, presentation, events, host trait
+|- window.rs            top-level window records only
+|- input.rs             un-targeted pointer, key, and wheel records
+|- text_input.rs        bounded IME/edit-session state and events
+|- accessibility.rs     stable PlatformElementId tree, bounds, and actions
+|- system.rs            typed clipboard, picker, URL, permission, menu services
+|- recording.rs         bounded deterministic fake host
+|- validation.rs        shared record validation
+`- tests.rs             contract, recovery, redaction, and wire-shape tests
+
+tests/platform_host_firewall.rs
+
+Planned next:
+src/platform_host/runtime.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 target Cargo feature names are planned as `host-macos`, `host-windows`,
-`host-linux-wayland`, and `host-linux-x11`, with an optional `host-linux`
-aggregate. They are not public features until H0 lands. None may enable or
-import `appkit-native`, `gtk4-native`, `winui-native`, or the legacy
-widget-planning modules.
+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.
 
 The new modules are created beside the legacy directories rather than by
 renaming a control backend. This makes accidental content-widget reuse visible
 and lets each old backend be deleted after its replacement evidence exists.
 
+## H0 Transaction and Thread Contract
+
+`PlatformHost` is intentionally thread-affine. The trait does not require
+`Send` or `Sync`, so an H2-H4 implementation can stay on its owning OS event
+loop. Every public record crossing the boundary is `Send + Sync` and contains
+no native or GPU handle.
+
+The runtime prepares one complete `PlatformHostTransaction` at a monotonically
+increasing `PlatformHostRevision`. Validation runs before host mutation and
+enforces bounded command counts, finite geometry, stable accessibility ids,
+UTF-8 text ranges, sensitive-value rules, and unique per-revision presentation,
+accessibility, and system-request identities.
+
+Commit atomically applies the pending revision. A failed commit leaves that
+revision pending so the owner must explicitly retry or roll it back; rollback
+does not advance the last committed revision. Shutdown rejects a pending
+transaction, releases queued events, and makes later operations fail. The
+recording host keeps bounded diagnostic history with text-input and sensitive
+clipboard payloads redacted while preserving byte lengths and command shape.
+
 ## Delivery Plan
 
 The host track is named H0-H5. It is dependency-coupled to renderer milestones
@@ -237,7 +273,7 @@ accessibility gates require M4.
 
 ### H0 - Contract and dependency firewall
 
-Status: next.
+Status: complete.
 
 Deliverables:
 
@@ -251,15 +287,27 @@ Deliverables:
 Gates:
 
 - the contract contains no widget create/update/remove operation
-- platform-host records contain no `NativeElement`, portable style, Node,
-  toolkit object, or `wgpu` handle
+- platform-host records contain no `NativeElement`, portable style, Node.js
+  runtime value, toolkit object, or `wgpu` handle
 - semantic-only builds remain free of Graphics and platform dependencies
 - every host-facing record is bounded, deterministic, and `Send + Sync` where
   thread affinity does not require an owning executor
 
+Evidence:
+
+- all six H0/target marker features compile without a legacy renderer
+- the common `platform-host` dependency graph contains no Graphics or OS
+  toolkit package
+- 13 unit tests cover validation, stable ids, wire shape, atomic revisions,
+  commit failure, rollback, teardown, bounded storage, and redaction
+- three integration tests recursively audit source imports, Cargo feature
+  edges, the public feature gate, and absence of widget CRUD
+- `just verify` runs the H0 compile, dependency-graph, contract, and firewall
+  gates on every normal CI change
+
 ### H1 - Shared self-drawn window runtime
 
-Status: planned after H0; depends on the M3 presentation boundary.
+Status: next; depends on the M3 presentation boundary.
 
 Deliverables:
 
@@ -415,17 +463,16 @@ or dependency-boundary evidence.
 
 ## First Reviewable Commit Sequence
 
-1. Add H0 contract records, fake-host conformance, feature firewall, and tests.
-2. Add H1 shared frame orchestration and raw-surface presentation lifecycle.
-3. Present the rectangle-only shared calculator through the Windows host.
-4. Present the same rectangle-only calculator through the macOS host.
-5. Present it through Wayland, then add the separately gated X11 fallback.
-6. Land text shaping, editing, input/IME, and accessibility slices against the
+1. Add H1 shared frame orchestration and raw-surface presentation lifecycle.
+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.
+5. Land text shaping, editing, input/IME, and accessibility slices against the
    shared host contract, one subsystem at a time.
-7. Pass the full calculator cutover matrix on all three platforms.
-8. Delete WinUI/XAML, GTK4, and AppKit content-control code in independent
+6. Pass the full calculator cutover matrix on all three platforms.
+7. Delete WinUI/XAML, GTK4, and AppKit content-control code in independent
    platform commits while preserving the new shells.
-9. Switch defaults, examples, packaging, and documentation, then run the final
+8. Switch defaults, examples, packaging, and documentation, then run the final
    repository-wide dead-code and dependency audit.
 
 Each commit must leave the tree buildable for its declared feature set. No

docs/roadmap.md

@@ -188,6 +188,9 @@ The repository already provides:
 - a shared calculator state model, reducer, RSX component tree, and three
   platform entrypoints
 - AppKit, GTK4, and WinUI control backends used as migration baselines
+- an H0 zero-widget platform-host contract with stable accessibility identity,
+  bounded revision transactions, a recording host, target feature markers, and
+  executable dependency/source firewalls
 
 The independent Graphics repository has a versioned scene, stable draw IDs,
 canonical fingerprints, retained damage, affine transforms, clipping, opacity,
@@ -407,7 +410,7 @@ Acceptance gates:
 
 ## P0-H Self-Drawn Platform Host Track
 
-Status: architecture planned; implementation has not started.
+Status: H0 complete; H1 is next.
 
 This track turns the existing offscreen layout/scene/GPU boundary into real
 windows without moving component rendering back into an OS toolkit. All
@@ -421,7 +424,7 @@ migration rules, and verification matrix are recorded in
 
 ### H0 - Host contract and dependency firewall
 
-Status: next; may begin during M3.
+Status: complete.
 
 - add typed window, presentation, input, text-input, accessibility, and system
   service records under a new `platform_host/` boundary
@@ -433,14 +436,26 @@ Status: next; may begin during M3.
 Gates:
 
 - the contract exposes no widget create/update/remove operation
-- host records contain no component style, Node, toolkit object, or `wgpu`
-  handle
+- host records contain no component style, Node.js value, toolkit object, or
+  `wgpu` handle
 - semantic-only builds stay free of Graphics and platform dependencies
 - target features do not import or enable legacy renderer modules
 
+Evidence:
+
+- `platform_host/` owns bounded records for windows, presentation, raw input,
+  text input, stable-id accessibility, system services, and ordered events
+- `PlatformHostTransaction` validates one monotonic revision before mutation;
+  `RecordingPlatformHost` proves prepare/commit/rollback, failed-commit
+  recovery, bounded queues/history, redaction, and explicit shutdown
+- `platform-host`, `host-macos`, `host-windows`, `host-linux-wayland`,
+  `host-linux-x11`, and `host-linux` compile without enabling a legacy backend
+- 13 focused contract tests and three recursive source/feature firewall tests
+  cover the H0 gates; `just verify` includes their build, graph, and test lanes
+
 ### H1 - Shared self-drawn window runtime
 
-Status: planned after H0; depends on M3 presentation work.
+Status: next; depends on M3 presentation work.
 
 - transact scene, hit-region, accessibility, and window state as one committed
   host frame
@@ -730,15 +745,13 @@ A component or subsystem is complete only when:
 
 ## Immediate Commit Sequence
 
-1. Land H0 host contracts, fake-host conformance, target feature boundaries,
-   and dependency firewalls.
-2. Land H1 shared frame orchestration and raw-surface presentation lifecycle.
-3. Present the generic rectangle slice through the H2 Windows Win32 host.
-4. Present the same slice through the H3 macOS system-shell host.
-5. Present it through H4 Wayland, then the separately gated X11 fallback.
-6. Add text shaping/rasterization, hit testing, input, IME, and accessibility
+1. Land H1 shared frame orchestration and raw-surface presentation lifecycle.
+2. Present the generic rectangle slice through the H2 Windows Win32 host.
+3. Present the same slice through the H3 macOS system-shell host.
+4. Present it through H4 Wayland, then the separately gated X11 fallback.
+5. Add text shaping/rasterization, hit testing, input, IME, and accessibility
    against the shared host contract.
-7. Pass the shared calculator cutover matrix on all three platforms.
-8. Delete WinUI/XAML, GTK4, and AppKit content-control code and all final
+6. Pass the shared calculator cutover matrix on all three platforms.
+7. Delete WinUI/XAML, GTK4, and AppKit content-control code and all final
    consumers in reviewable, platform-scoped commits while preserving the thin
    OS shells.

justfile

@@ -311,6 +311,11 @@ check-core:
     cargo check --locked --no-default-features --features graphics --lib
     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
+
+# Compile every zero-widget host marker without a legacy renderer
+check-platform-host:
+    cargo check --locked --no-default-features --features platform-host,host-macos,host-windows,host-linux --lib
 
 # Prove semantic-only builds do not acquire Graphics or wgpu
 check-core-graph:
@@ -323,6 +328,22 @@ check-core-graph:
         exit 1
     fi
 
+# Prove the H0 contract graph contains no renderer or OS toolkit dependency
+check-platform-host-graph:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    host_graph="$(cargo tree --locked --no-default-features --features platform-host --prefix none)"
+    if grep -Eq '^(a3s-graphics|wgpu|gtk4|gdk4|gsk4|winio-winui3|windows-collections|objc2-app-kit) ' <<<"$host_graph"; then
+        echo "renderer or toolkit dependencies entered the H0 platform-host graph" >&2
+        exit 1
+    fi
+
+# Run the zero-widget platform-host contract and firewall suites
+test-platform-host:
+    cargo test --locked --no-default-features --features platform-host --lib platform_host::
+    cargo test --locked --no-default-features --features platform-host --test platform_host_firewall
+
 # Run native-feature library tests for this operating system
 test-native:
     #!/usr/bin/env bash
@@ -361,14 +382,15 @@ winui-input-smoke EVIDENCE:
 
 # Lint every target and deny high-confidence Clippy and Rust warnings
 clippy:
-    cargo clippy --locked --all-targets --features appkit,winui,gtk4,gpu -- -A clippy::all -D clippy::correctness -D clippy::suspicious -A clippy::unnecessary_get_then_check -D unused
+    cargo clippy --locked --all-targets --features appkit,winui,gtk4,gpu,platform-host -- -A clippy::all -D clippy::correctness -D clippy::suspicious -A clippy::unnecessary_get_then_check -D unused
 
 # Build crate documentation and fail on rustdoc warnings
 doc-check:
     RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --document-private-items
+    RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-default-features --features platform-host --no-deps --document-private-items
 
 # Run the full local verification suite
-verify: fmt-check check-core check-core-graph clippy doc-check test test-examples test-platforms test-graphics diff-check
+verify: fmt-check check-core check-core-graph check-platform-host check-platform-host-graph clippy doc-check test test-examples test-platforms test-platform-host test-graphics diff-check
 
 # Run dogfood reducer and protocol-boundary regression tests
 dogfood-regression: