Introducing Reconstructive UI

Building the complete UI structure on each update

2026.09.18

We propose reconstructive UI as a name for the UI programming paradigm used byShirei. In this model, application code updates the view by rebuilding its complete structure. This article explains the paradigm and why we think it deserves a more descriptive name than “immediate mode GUI.”

Imagine a small contact management application. Its window contains a toolbar, a list of contacts, and a footer showing the number of contacts. Each contact has a name and an email address. A setting controls whether email addresses are visible.

To build this interface, the application uses primitives provided by a UI framework: create a container, add a label, add a button, set some attributes. Application code combines these primitives into larger pieces, such as a contact row or a toolbar, and combines those pieces into the complete view.

We can call this code the UI builder. Here is a simplified example, using pseudocode:

build contact window:
    column:
        toolbar:
            button "Add contact"
            checkbox "Show email addresses", settings.showEmail

        column:
            for contact in contacts:
                row:
                    label contact.name
                    if settings.showEmail:
                        label contact.email

        label "{contacts.count} contacts"

The builder traverses application data and uses the framework's primitives to establish what belongs in the view. Functions, loops, and conditionals let us organize this work using ordinary programming techniques.

What does running this code produce?

At this stage, it produces a UI structure. For two contacts with email addresses visible, that structure looks roughly like this:

Column
    Toolbar
        Button: Add contact
        Checkbox: Show email addresses
    Column
        Row
            Label: Alice
            Label: alice@example.com
        Row
            Label: Bob
            Label: bob@example.com
    Label: 2 contacts

The structure records the elements, their contents and attributes, and their relationships. It gives the framework the information it needs to display the interface. The framework can resolve sizes and positions, prepare drawing commands, and produce pixels on the screen.

Conceptually, the pipeline looks like this:

Application data
    ↓
UI builder
    ↓
UI structure
    ↓
Layout and rendering
    ↓
Pixels on the screen

Building the structure and rendering it are separate stages. A call that adds a label to the structure does not have to draw text immediately. Its final position may depend on other elements that the builder has yet to supply.

So far, this only explains how to build the initial view. Now suppose the user adds a third contact.

We add the contact to the application's data and run the entire UI builder again. The loop produces three rows, and the footer contains the new count. The builder also supplies the toolbar, even though its contents remain the same.

If the user hides email addresses, we change the setting and run the entire builder again. This time, the conditional omits the email labels. If the user changes the sort order, the loop visits the contacts in the new order, and the structure reflects that order.

The code that builds the view is also the code that updates it.

This is how Shirei's API works. It provides primitives for building the UI structure, and application code uses them to reconstruct the whole view whenever it needs updating. The existing terms do not describe this design well: “immediate mode” suggests immediate graphics rendering, while “declarative” suggests a functional style rather than Shirei's procedural construction. “Reconstructive” names the update model directly:

Reconstructive UI is a paradigm of UI programming where application code rebuilds the entire UI structure on each UI update.

Each update runs the entire builder, including the parts whose output stays the same. Splitting that builder into functions helps organize the code; it does not turn those functions into independently updated regions.

In this paradigm, application code expresses the whole view for the current data. Adding, omitting, and rearranging elements all follow from executing the builder again. The application does not need a corresponding set of commands to insert, remove, and move persistent widget objects.

The paradigm describes how application code builds and updates the UI structure. It leaves scheduling, state retention, layout, and rendering to the framework.

For example, reconstruction does not prescribe a refresh rate. A framework can run the builder continuously, or it can wait until input or application activity requires an update. Shirei reconstructs the view when needed; it does not require the builder to run sixty times per second.

State retention is optional too. Shirei preserves component identity and state across builds, but a framework without this retention can still expose a reconstructive API.

Layout is another independent choice. A builder can provide constraints for an automatic layout system, explicit positions, or a combination of both. Each approach supplies information that the framework uses to place the elements.

The same freedom applies to rendering. The framework decides how to turn the complete structure into pixels, including which work it can reuse across builds.

A reconstructive API can therefore sit above a retained rendering system. There is no contradiction: the terms describe different stages of the pipeline.

Why introduce a new term when “immediate mode UI” already exists?

Shirei's API can be described as immediate mode. But the term carries a specific meaning in graphics programming. Microsoft'sRetained Mode Versus Immediate Mode describes an immediate-mode graphics API as one where application code issues drawing commands for each frame, and the graphics library does not retain a scene model between frames. Applying that terminology to UI construction brings those rendering associations along with it.

We propose “reconstructive UI” because it directly names the update model without suggesting how or when rendering happens.

Isn't rebuilding the whole UI wasteful?

The UI structure is just data: containers, attributes, text, and relationships. Creating a basic data structure in memory is generally very fast. Partial updates to a retained structure have their own cost: tracking changes, identifying the affected elements, and keeping the structure synchronized with application data. That bookkeeping can cost more than simply building the structure again. Doing fewer structural updates does not automatically mean doing less work.

The objection does matter when the builder performs expensive operations. Every reconstruction repeats that work, so a builder that reads files or processes a large dataset can make even a small UI slow.

Expensive data processing belongs off the UI thread. Background work prepares the data and makes the results available to the UI; the builder reads that data and constructs the view. This separation keeps the work repeated during UI updates small, even when the application itself performs substantial computation.

How can anything persist if the structure is rebuilt?

Rebuilding the structure does not require the framework to discard everything it knows about the elements in it. A framework can identify corresponding elements across successive builds and associate retained information with those identities.

Shirei keeps a parallel tree for component identity and state. The container tree supplied by the builder describes the current view; the parallel tree lets Shirei recognize components and preserve information across builds. Reconstructing a component's structure therefore does not necessarily create a new component identity or reset its state.

How Shirei retains component identity and state explains the mechanics, including implicit identity, explicit keys, and retained component state.