feat: add native layout scene pipeline

Author: Roy Lin

README.md

@@ -39,6 +39,8 @@ The crate provides:
   announcements, and field-level backend capability reporting
 - Tailwind-compatible utility parsing into a platform-neutral native style
   model
+- versioned 1/64-point layout snapshots, stable keyed hit regions, explicit
+  projection diagnostics, and Native IR-to-Graphics rectangle lowering
 - a built-in `rsx_ui` component registry plus calculator, dogfood, and
   component-playground applications
 
@@ -326,6 +328,11 @@ constraints, and explicit keypad sizing. Their semantics and layout intent are
 therefore shared. Exact pixels still follow each native toolkit's control
 metrics, font fallback, DPI scaling, and rendering behavior.
 
+The self-drawn rectangle fixture now compiles that same shared calculator tree
+into versioned layout records and a Graphics Scene. It pins deterministic
+layout/scene fingerprints, retained software output, and a reviewed local DX12
+readback threshold; text and real window presentation remain roadmap work.
+
 Direct native examples follow the same naming pattern:
 
 ```sh
@@ -413,6 +420,7 @@ libraries.
 
 - [Runtime and protocol architecture](docs/architecture.md)
 - [Renderer field inventory](docs/renderer-field-inventory.md)
+- [Layout and Graphics scene contract](docs/layout-scene.md)
 - [Native app shell](docs/app-shell.md)
 - [Native packaging](docs/packaging.md)
 - [React Aria native direction](docs/react-aria-native.md)

docs/architecture.md

@@ -161,6 +161,17 @@ enumerates all current `PortableStyle` fields and exhaustively assigns native
 roles and normalized input events to their first complete delivery milestone.
 Later-milestone fields remain explicit diagnostics in earlier renderer slices.
 
+The [layout and scene contract](layout-scene.md) now implements the first
+generic vertical slice. `NativeElement` keys become collision-safe stable layout
+paths; boxes are quantized to 1/64 logical point; paint, hit regions, and
+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.
+
 The remaining dependencies stay one-way:
 
 - `ComponentCx`, RSX parsing, and `rsx_ui` authoring compile outward-facing

docs/layout-scene.md

@@ -0,0 +1,121 @@
+# Layout and Scene Contract
+
+Updated: 2026-08-01
+
+The first self-drawn renderer slice consumes the existing `NativeElement`
+tree. It does not define a calculator-specific visual tree or copy component
+state into a renderer model.
+
+```rust
+use a3s_gui::drawing::{scene_from_layout, LayoutSceneOptions};
+use a3s_gui::layout::layout_native_tree;
+use a3s_gui::Size;
+
+let layout = layout_native_tree(&native, Size::new(410.0, 620.0))?;
+layout.require_supported()?;
+let scene = scene_from_layout(&layout, LayoutSceneOptions::default())?;
+# Ok::<(), a3s_gui::GuiError>(())
+```
+
+Layout is available in semantic-only builds. Graphics scene extraction is
+available only with the `graphics` feature, while rendering remains behind
+`software-reference` or `gpu`.
+
+## Versioned records
+
+`LayoutSnapshot` schema version 1 contains:
+
+- logical surface size and boxes quantized to 1/64 logical point
+- flat `LayoutNodeRecord` values with role, parent identity, border/content
+  boxes, inherited clip, z-index, paint order, hit eligibility, and box paint
+- separate `LayoutHitRegion` values keyed to the same semantic elements
+- structured warnings and errors with element and field attribution
+- deterministic serialization, fingerprinting, and node-level layout diffs
+
+`LayoutElementId` is a path of byte-length-prefixed sibling keys. Reordering a
+sibling does not change its identity, and `/` or other punctuation in a key
+cannot make two paths collide. The Graphics adapter derives each `DrawId` from
+that path plus a stable paint slot.
+
+The snapshot contains no labels, values, passwords, native handles, GPU
+objects, or product state.
+
+## Implemented M3 slice
+
+The current deterministic box path implements the subset needed by the shared
+calculator:
+
+- vertical block flow and no-wrap horizontal/vertical flex flow
+- explicit, percentage, minimum, and maximum size with border/content sizing
+- physical and horizontal-writing logical padding, margin, inset, and border
+- row/column gap, source order, integer order, main/cross-axis alignment, and
+  stretch for auto cross sizes
+- relative, absolute, and fixed positioning
+- overflow rectangle clipping, visibility, opacity, pointer eligibility,
+  simple sibling z-order, and cumulative descendant opacity
+- solid color backgrounds, per-edge solid borders, circular corner radii, and
+  opaque rounded background/border composition
+
+The portable Tailwind contract historically treats a positive border width as
+solid when no explicit border style is present. Explicit `none` and `hidden`
+still suppress the border. The layout path preserves that behavior so it
+matches the existing native backends without depending on browser Preflight.
+
+Full flex growth and shrinkage, wrapping, grid/table layout, vertical writing,
+baseline alignment, elliptical radii, CSS expression evaluation, inherited or
+functional colors, and complete stacking contexts are not claimed by this
+slice.
+
+## Projection diagnostics
+
+Every effective `PortableStyle` field is checked against the executable
+[renderer field inventory](renderer-field-inventory.md).
+
+- A later-milestone field produces a warning. Text and control roles therefore
+  retain their M3 boxes while their visible content remains an explicit M4
+  item.
+- An M3 field or value that this slice cannot project produces an error.
+- A property retained in `PortableStyle::unsupported` produces an error.
+- `scene_from_layout` rejects any snapshot containing an error before it emits
+  a draw command.
+
+This lets inspection tools display partial boxes without allowing a required
+calculator style to disappear silently from an accepted scene fixture.
+
+## Retention and paint ordering
+
+Repeated snapshots have identical fingerprints. `LayoutSnapshot::diff`
+reports stable-key additions, removals, changed records, dirty bounds, and
+surface rebuilds. Graphics performs the subsequent primitive diff and retained
+damage calculation.
+
+A parent background is emitted before its descendants. Siblings are placed by
+z-index, flex order, and source order, and each subtree remains contiguous.
+This is sufficient for the calculator and simple overlays; complete CSS
+stacking-context behavior remains M3 work.
+
+Overflow clips apply to descendants and are intersected through the tree.
+Fixed-position descendants use the viewport rather than inheriting an ordinary
+ancestor clip. Hit regions use the same quantized identity and visible bounds
+but remain separate from paint commands.
+
+## Calculator evidence
+
+`tests/calculator_layout_scene.rs` compiles the existing shared calculator RSX,
+lowers it through `RsxCompilerBridge`, wraps the real 410 by 620 window native
+tree, and then uses this generic path. The fixture pins:
+
+- layout fingerprint `16529597026056060935`
+- Graphics scene fingerprint `2100550662756266801`
+- exact repeated software output and retained no-damage behavior
+- background, transparent exterior, ordinary-key, and equals-key pixels
+
+On the 2026-08-01 local Direct3D 12 run, GPU readback differed from the software
+reference at 940 of 254,200 pixels (0.370%), all around rasterized edges, with a
+maximum channel delta of 91. The reviewed non-text gate allows at most 0.5% of
+pixels and a maximum channel delta of 96 while requiring the listed solid
+pixels to match exactly.
+
+An unavailable adapter skips the local GPU test and is not cross-platform
+evidence. Metal and Vulkan runs, real window presentation, text, input, IME,
+and accessibility remain separate roadmap gates.

docs/roadmap.md

@@ -219,7 +219,7 @@ Acceptance gates:
 
 ### M1 - GUI architecture cleanup and dependency integration
 
-Status: current.
+Status: complete.
 
 Landed evidence:
 
@@ -238,8 +238,8 @@ Landed evidence:
 - the versioned renderer inventory accounts for all 504 `PortableStyle`
   fields, every `NativeRole`, all normalized input events, and the focus,
   overlay, text, and accessibility records required by cutover
-
-Remaining work is the first `NativeElement` layout-to-scene adapter.
+- the first generic `NativeElement -> LayoutSnapshot -> Graphics Scene`
+  adapter landed with stable keyed identity and explicit projection diagnostics
 
 Deliverables:
 
@@ -285,7 +285,28 @@ Acceptance gates:
 
 ### M3 - Generic layout and scene vertical slice
 
-Status: planned after M2.
+Status: current.
+
+Landed evidence:
+
+- layout schema version 1 records 1/64-point quantized boxes, stable
+  length-prefixed element paths, paint, clips, z/order, and separate hit regions
+- the generic engine covers the calculator's row/column flow, box model,
+  explicit/min/max size, alignment, absolute positioning, overflow clipping,
+  opacity, and solid rectangle paint without a calculator renderer model
+- unsupported M3 fields are error diagnostics rejected by scene extraction;
+  later role/style work remains visible as warnings
+- stable layout diffs feed the Graphics scene/damage diff, and stable layout
+  paths derive retained `DrawId` values
+- the existing shared 410 by 620 calculator Native IR pins layout fingerprint
+  `16529597026056060935` and scene fingerprint `2100550662756266801`
+- repeated software output is byte-identical with no retained damage; the local
+  Direct3D 12 readback passed the reviewed 0.5%/96 non-text threshold with
+  exact solid-color checkpoints
+
+Remaining work includes full flex growth/shrink/wrap, complete stacking
+contexts, redraw scheduling, Metal/Vulkan evidence, and real thin-host window
+presentation.
 
 Deliverables:
 

src/drawing.rs

@@ -10,6 +10,9 @@ pub use a3s_graphics::{
     Primitive, Rect, Scene, SceneBuilder, Size, StrokeRect, SCENE_SCHEMA_VERSION,
 };
 
+mod layout_scene;
+pub use layout_scene::{scene_from_layout, LayoutSceneOptions};
+
 #[cfg(feature = "gpu")]
 pub use a3s_graphics::{
     GpuBackend, GpuBackendPreference, GpuCapabilities, GpuDeviceType, GpuFrame, GpuPowerPreference,