fret-ui

fret-ui is the UI runtime contract layer for the Fret workspace.

It provides the mechanisms that higher layers build on:

• Declarative element authoring + reconciliation (GPUI-style direction),
• Layout + hit testing + paint orchestration (runner/host driven),
• Cross-frame state storage and stable identity,
• Focus/input routing surfaces and debug snapshots.

This crate is not intended to be a policy-heavy component library. Radix/shadcn-style interaction policies (dismiss, focus trap/restore, hover intent, default sizing/padding conventions, etc.) belong in the ecosystem layer (fret-ui-kit, fret-ui-shadcn) rather than here.

Module ownership map

The crate is large; treat it as a set of subsystems:

• src/declarative/: frame-to-frame element tree building and reconciliation.
• src/tree/: runtime tree representation, layout/paint passes, hit testing, and debug stats.
• src/elements/: builder helpers and element runtime utilities.
• src/element.rs: element property types (including layout/text/scroll props) and runtime-facing contracts.
• src/layout/: layout engine glue (constraints, pass, engine).
• src/text/: text input/editing surfaces (IME integration lives here, policy lives above).
• src/scroll/ + src/virtual_list/: imperative scroll handles and the virtual list virtualizer.
• src/theme/: token/config/theme snapshot plumbing (policy lives above).
• src/overlay_placement/: placement helpers for overlay/popup positioning (arbitration policy is tracked separately in workstreams).
• Crate-root modules: thin glue/utility pieces that have not yet been regrouped.

Public surface

Prefer importing from fret_ui’s re-exports in src/lib.rs (e.g. UiTree, UiHost, ScrollHandle, TextInputStyle). Internal modules are being regrouped as part of the bottom-up fearless refactor; relying on deep paths makes churn more likely.

Local refactor gates

• Fastest loop: cargo nextest run -p fret-ui
• Formatting: cargo fmt