Skip to content

Architecture

Follow compilation, state ownership, threads and the native adapter boundary.

On this page

Architecture overview

Inrux target architecture: applications and compiler tools, framework modules, engine-neutral service contracts, native adapters, fallback providers and thread ownership.

Open the full-size architecture SVG to read the labels or zoom in.

Inrux owns its public component, styling, state and service contracts. Native engine details remain behind inrux-adapter and the selected private binding. The public inrux facade re-exports application APIs; the compiler is a separate build dependency.

Reading the diagram

Read from the application at the top toward native execution at the bottom. The three adapter columns show backend choices. A normal application selects one backend when building; it does not run all three or move a live window between them.

Area in the imageWhat it means for your application
Applicationmain.rs mounts App.iru. You compose reusable UI components and import normal Rust modules for services and business rules.
Build and developer toolsThe CLI, .iru compiler, Cargo and rustc turn your source into a native program. Editor tools use compiler metadata; they do not execute rendering services.
Components and compositionInrux defines props, models, emitted events, child content and retained identity. Native widget types do not enter those public contracts.
Styling and layout rulesYour CSS subset and Rust styles describe the appearance and sizing you want. Inrux resolves those rules before a selected provider executes layout or painting.
Core and runtime orchestrationSignals, computed values, scopes and component ownership describe application state. The coordinator serializes updates, and bounded workers handle slow tasks.
Engine adapter contractsInrux defines the behavior a native service must provide, including values, errors, capabilities and ownership. Application components call these contracts without checking the backend name.
Private adapters and native infrastructureEach binding owns its engine objects, native events and rendering resources. It translates between Inrux contracts and egui, GPUI or Masonry.
Fallback providersAn adapter can use an existing library or a focused implementation when a native service cannot satisfy the contract. A fallback is a service provider, not a fourth GUI backend.

Delegation and fallback selection

The adapter should use a native implementation only when it preserves the required Inrux behavior. If it cannot, the adapter selects a suitable fallback. Both choices must produce compatible results for the component above them.

For example, a future native layout provider could replace Taffy for one backend after passing sizing, identity and input-geometry checks. It would become the layout authority for that subtree; the framework should not calculate the same layout twice. Today all three bindings select Taffy. The diagram does not claim that native layout substitution already works.

Keep reusable providers shared when several adapters need them. Keep engine-specific details private when only one binding uses them. Compile the providers needed by the selected backend. Delegating a method does not by itself prove that it is faster; measure translation, allocation and caching costs too.

Arrows and execution ownership

Descriptions, resolved values and commands travel toward the selected adapter. Input events and measurements return to the framework through engine-neutral values. Keep native handles on their owning UI thread rather than passing them into application components or worker jobs.

The thread box summarizes ownership, not a sequence of threads that each frame must visit. The UI thread handles native input, layout and painting. The coordinator handles state and view construction. Workers receive owned task inputs and return typed completions to the coordinator while their owning mount remains valid.

Performance policy and validation

The performance strip describes goals across modules. Stable identities and bounded/coalesced update paths are part of the current foundation. Selective invalidation, virtualization and complete incremental native-tree updates are not all implemented.

The validation line describes the order for accepting an optimization: check the contract, test native interactions, then compare release workloads. A backend must preserve behavior before a benchmark can justify choosing it as the default. Inrux has no certified default engine or published overall performance ranking yet.

Compilation

  1. Source filesApp.iru, explicit component imports and style blocks or precompiled standalone CSS.
  2. inrux-compilerValidate syntax/imports; produce Rust code, typed style rules and editor source metadata.
  3. Cargo and rustcType-check props/handlers and compile generated code with normal dependencies.
  4. Native binaryLink the selected GUI backend and the reachable application code.
Cargo compiles generated Rust together with your Rust modules. Runtime-selected imported candidates remain reachable.

The compiler lowers top-level typed declarations in <rust> into retained State fields and a generated constructor. Initialization runs once per component instance; imports, functions and type declarations stay in Rust module scope. This transformation happens before rustc checks types. There is no runtime parser. Default <rust> blocks need no user-written setup function; <rust explicit> selects an authored State and setup function instead.

Custom components must be explicitly imported. The compiler follows the reachable imported graph. Imported candidates used in runtime conditionals remain part of the graph; an unimported custom tag is an error. This is compile-time reachability, not runtime code loading. rustc/linker optimization determines final machine-code retention.

.iru styles and optional standalone CSS compilation produce typed Rust rules. Matching uses immutable indexes plus specificity/source-order and viewport/state predicates. Dynamic state still requires runtime evaluation; compiling CSS does not remove all styling/layout work.

Runtime threads

  1. UI threadReceive native events; manage layout, input, painting and native objects.
  2. Application coordinatorProcess queued handlers; update state and computed dependencies; publish component descriptions.
  3. Bounded task poolRun expensive work with owned inputs and cooperative cancellation.
  4. Typed completion to coordinatorApply results only while the owning mount/generation remains valid.
  5. Newest description to UI threadTranslate shared geometry and glyph pixels into native drawing and controls.
Events and frame descriptions cross bounded queues. Slow work can still stall its owning thread.

A coordinator serializes application event/state work. Native objects remain on the UI thread. Expensive blocking work belongs in tasks; callbacks and rendering can still stall their owning thread. Bounded queues, cancellation and mount generations control lifetime and stale completions; they are not a guarantee that the UI can never lag.

The current hosts consume published descriptions and perform shared layout/native translation. Fully incremental layout, persistent native-tree updates and broad cache reuse are still optimization work.

Adapter boundary

inrux-adapter defines startup, window/error types, capability checks and service contracts without GUI engine types. inrux-egui, inrux-masonry and inrux-gpui own native widgets/resources, event translation and painting. Components are written once above this boundary; private native bindings implement the necessary primitives for each engine.

An implementation may delegate a service to a native engine when it satisfies Inrux semantics, or select an existing library/fallback. There must be one layout authority for a subtree, rather than two competing layout passes. All three current bindings select the shared Taffy provider and shared Parley/Swash text provider. Alternative native layout delegation is not delivered yet.

Service contracts need explicit ownership, errors, capabilities, threading and invalidation. Engines do not gain public styling behavior simply because an upstream feature exists; shared behavior must pass conformance checks. See operational service APIs.

Styling and text

Applications own themes, tokens, classes and component visual recipes. Framework components supply behavior and minimal defaults that applications can override. The CSS guide describes the supported subset; public parts expose selected inner surfaces without native handles.

inrux-text shapes with Parley, produces shared caret/selection geometry and rasterizes glyph tiles with Swash. Native backends upload these pixels. Fonts register before mounting. Common geometry/pixels reduce cross-engine differences; compositor output, fallback coverage, accessibility and IME still need platform validation. See text rendering.

Backend selection and measurement

The facade has no default GUI engine. Applications enable one engine feature and rebuild to switch compatible code. Backend-native types stay out of application components. Runtime migration of live windows is not supported. Some primitives remain engine-specific; unsupported capabilities must be reported rather than silently ignored.

Benchmark native baselines and framework applications under the same workload. Include translation, allocations/caching, layout count, startup, idle/heavy memory, input latency and frame-time distributions. There is no published overall performance ranking or certified default engine yet. The status page records the main gaps.

Inrux · Built with Nuxt Content, IPEX, and Akaza UI.