Quoin’s architecture separates three concerns: a small trait contract, five adapters that implement it natively, and shared machinery that keeps the adapters consistent. Everything composes through the quoin facade crate.
The layers
Section titled “The layers” your app / your hook library │ quoin (facade) ← feature flags pick one backend ┌─────────┼─────────┐ quoin-macros quoin-ui quoin-core ← contract + tooling │ │ │ quoin-macros-core quoin-style ← parsing & codegen │ ┌────┴─────┬──────────┬───────────┬──────────┐ quoin-gpui quoin-leptos quoin-dioxus quoin-xilem quoin-floem └──────────┴──────────┴─────┬─────┴──────────┘ shared machinery in quoin-core join · globals · NotifierSignal · batch · poolThe contract layer
Section titled “The contract layer”quoin-core defines the traits every adapter implements: Signal<T>, ReactiveContext, Executor, plus the blanket extension traits (SignalExt, ExecutorExt, ReactiveContextExt) that are implemented once, generically, so every adapter gets them for free with zero per-adapter code. Portable conveniences also live here: derived/memo/zip, resources, batching, cancellation, spawn_local, timers, and pooling.
The adapter layer
Section titled “The adapter layer”Each adapter crate (quoin-gpui, quoin-leptos, quoin-dioxus, quoin-xilem, quoin-floem) provides a concrete ReactiveContext for its framework. Adapters share machinery that used to be hand-copied five times:
- join — the
JoinHandlelifecycle (await / abort / detach / abort-on-drop) is written once; only the “how do we cancel the underlying task” part differs per framework. - globals — the thread-local,
TypeId-keyed store behindprovide_global/use_globalon the pull-based adapters. - NotifierSignal — the cell-plus-notifier signal implementation with batch awareness.
On wasm32, the Leptos and Dioxus executors run futures on the main thread via wasm_bindgen_futures; on native they use threads like the other adapters.
The macro layer
Section titled “The macro layer”quoin-macros is a thin proc_macro boundary over quoin-macros-core, which parses component!/quoin_render!/effect! once and emits per-backend code through FrameworkEmitter implementations. Class strings are parsed by quoin-style into a typed IR (Decl lists per state) — one parse, many lowerings, no runtime class parsing. Unrecognized classes become compile errors with did-you-mean suggestions.
The protocol and tooling layer
Section titled “The protocol and tooling layer”quoin-uideclares the Universal Component Protocol traits and node vocabulary;quoin-ui-gpuiis the first full implementation.quoin-testkitsuppliesTestContextand deterministic executors for headless testing.quoin-devtoolswraps any context withInstrumentedand records events into a ring buffer.quoin-conformanceholds the shared suite that every adapter must pass — the mechanism behind backend parity.
Facade composition
Section titled “Facade composition”The quoin facade re-exports all of the above behind feature flags. Framework features are mutually exclusive (a compile_error! fires otherwise); testkit and devtools are additive. This keeps a typical application at one dependency line while letting framework-free libraries depend on quoin-core alone.
Next steps
Section titled “Next steps”-
The Reactivity ModelHow the contract maps onto pull-based and fine-grained frameworks.
-
CratesThe per-crate reference table.
