BlankAppLayout

The layout module for the blank_app scaffold. It builds a single UI screen from the engine's raw, CSS-parity widget tree and wires up one interaction: a +1 button that increments a counter and re-renders.

This is the file you edit. Replace the build tree with your own widgets.

The contract

A UiPanel component points its source at this module and calls mount(ctx), where ctx = { entity, entityId, data, state? }. mount returns the handlers the panel drives each frame:

function M.mount(ctx)
    local state = ctx.state or { count = 0 }   -- 1. state is the source of truth
    local function build() return { --[[ widget tree ]] } end
    ui.registerScreen("blank_app", build())    -- 2. register the tree as a screen
    return {
        state = state,
        update = function(dt) end,             -- 3. per-frame work (no-op here)
        onCallback = function(id, data)        -- 4. an interaction lands here
            if id == "blank:inc" then
                state.count = state.count + 1
                ui.updateScreen("blank_app", build())  -- mutate, then re-render
            end
        end,
        destroy = function() ui.unregisterScreen("blank_app") end,
    }
end

• state is returned so the panel hands it back on a live-reload — your count survives an edit.
• update(dt) runs every frame; leave it a no-op when nothing animates.
• onCallback(id, data) receives every widget's callback id. Mutate state, then call ui.updateScreen(name, build()) to publish the new tree.
• destroy() unregisters the screen when the panel goes away.

The raw widget tree

A node is a table: { type = "...", props = {...}, style = {...}, children = {...} }.

• Containers lay out their children: vertical (column), horizontal (row).
• Leaves carry content: label (text in props), button (text + onClick in props).
• props is the widget's data and behaviour — a label's text, a button's onClick callback id.
• style is CSS: padding, gap, background, color, fontSize, fontWeight, borderRadius, borderWidth, borderColor, minWidth, minHeight, boxShadow, and the rest of the box model.

The tree is a pure function of state: to change what shows, rebuild the tree and call ui.updateScreen. There is no retained widget object to mutate.

Interactivity

An interactive widget carries a string callback id in props (this button's onClick = "blank:inc"). When the user clicks, the engine delivers that id to onCallback here. onClick works on any widget — a label, a horizontal row, an image — not just a button.

Interaction runs in play, not edit: enter play and click the button to see the count rise.

Discover the surface

• The gui toolbox's widgetTypes tool lists every type.
• Its widgetProps tool lists one type's props.
• @builtin::examples.ui.* are complete CSS-parity screens (dashboard, sci-fi HUD, RPG inventory) in this exact model — read one before building.
• The UI and styling guides cover the model and the full style surface.