Crate lingxia_surface 

lingxia-surface — the platform-agnostic core of the Adaptive Surface Layout model (see docs/draft/adaptive-surface-layout.md).

Pure Rust, no UI: the Surface Graph, its invariants and state transitions, the two-axis derivation into DerivedLayout, and the Host arbitration pure function. Each platform skin binds the DerivedLayout output.

Structs

DerivedLayout

Shared-core output bound by each platform skin. The pure core view: the resolved sizeClass/forms/bottomOwner and the authoritative layoutTree. The renderable, skin-bindable contract is LayoutPresentationPlan (derived from this graph), not this type.

FloatSpec

Minimal semantics carried only by float surfaces (§1.1).

LayoutPresentationPlan

The stable, complete render contract a skin binds. Unlike the pure-core DerivedLayout, this flattens the graph into the renderable view any skin needs: ordered mains, asides (with edge + preferred size), floats, and the full id-only tree. Derived from the graph so the shared core output isn’t bound to one skin’s needs.

OpenOutcome

Result of opening a surface after reuse/arbitration has resolved its identity and role. Callers must bind handles to resolved_surface_id, not to the request id: a reused URL aside keeps the original runtime id.

Placement

Placement hint (input). Authoritative layout is the LayoutTree (output).

PlanAside

One aside in the LayoutPresentationPlan: the surface id, the requested edge, and its preferred size. Skins read split_form to decide whether these asides dock beside the main or present full-screen on compact.

PlanAsideSlot

One aside slot in the LayoutPresentationPlan: the aside area holds at most one region per content kind (lxapp / browser / native); the region’s contents are its tabs, in open order. Skins render ONE docked panel per slot, with a header tab strip when children has more than one entry.

PlanFloat

One float in the LayoutPresentationPlan: the surface id plus the render-relevant FloatSpec semantics (anchor, dismiss, modal). Floats are popups above the layout and are never in the tree, so the skin reads this list to know which popups to show and how each behaves. The reconciler is the single authority for float visibility.

Policy

Tunable arbitration policy. Defaults are the spec’s cross-platform defaults.

Surface

One node in the Surface Graph.

SurfaceGraph

One window’s graph. Surfaces are kept in insertion order so that “adjacent main” succession and “oldest aside” replacement are deterministic.

SurfaceInteraction

User interaction contract for a dynamically presented surface.

SurfaceManager

One window’s stateful surface driver.

Enums

Axis

BottomOwner

Who owns the bottom bar in compact.

Decision

Structured outcome of a request (§3.1).

Edge

Which edge a surface docks to (asides) or anchors from.

FloatAnchor

How a float surface anchors.

FloatDismiss

How a float surface is dismissed.

LayoutTree

Authoritative layout produced by the Host (output), referencing surfaces only by id. Overlay/float surfaces never appear here.

Role

Relationship of a surface to the main content. The single core abstraction behind every platform skin (window / panel / sheet / tab …).

SizeClass

Available-width band. Aligned to Material breakpoints and computed from the full client-area width, not the physical screen. Ord follows the declared order (Compact < Medium < Expanded).

SlotKind

Aside slot grouping: the aside area holds at most one region per render engine — lxapp, browser, native — and multiple contents of one kind live inside that region as tabs.

SplitForm

How asides (the split axis) render. sheet belongs to float, not here.

SurfaceContent

What a surface shows. Only two kinds: a declared catalog entry (resolved by the host from lingxia.toml) or an ad-hoc web page.

SurfaceOwner

Owner scope: decides when the surface is closed (§5).

SurfaceState

Runtime state of a surface.

SwitcherForm

How the main-switcher renders on this platform/size.

Constants

DEFAULT_HYSTERESIS

Default hysteresis margin to avoid breakpoint thrashing.

Functions

arbitrate

Run arbitration. Pure: clones the graph, applies the resolved request, and returns the new graph plus the decision. The result graph is always valid.

normalize_initial_url

Stable key for a URL aside’s initial URL. Navigation never mutates the graph’s stored URL, so reuse remains tied to the initial request. Query and fragment bytes remain part of the key.

Type Aliases

SurfaceId

Stable identifier of a surface within a graph.