Public API contractVerified 2026-08-27Not yet executable

GUI snapshot, transaction, and change-event members are present in the API 4 registry; public live acceptance is not recorded.

Automate a GUI

Use a fresh snapshot and one guarded transaction. If the screen changes, observe again before clicking.

The safe loop

1. Call hexis.gui.snapshot({}).
2. Find a slot from its item evidence.
3. Submit one hexis.gui.transact operation with the current screen and slot references.
4. Await the result.
5. Snapshot again or consume a gui.changed event.

Your bundle needs gui.read to observe and gui.interact to transact.

Activate one slot

local observed = hexis.gui.snapshot({})
if observed.status ~= "open" then return end

local screen = observed.screen
local target = screen.slots[14]
local result = hexis.await(hexis.gui.transact({
    screen = {
        generation = screen.generation,
        revision = screen.revision,
    },
    operation = {
        kind = "activate",
        target = target.ref,
    },
}), {timeout = 2})

Slot indexes are zero-based. A slot reference belongs to one observed screen generation and revision. It is evidence, not permanent permission to click the same index.

Add up to eight guard references when other slots prove that the operation is still safe:

operation = {
    kind = "activate",
    target = target.ref,
    guards = {screen.slots[50].ref},
}

Close the screen

hexis.gui.transact({
    screen = {generation = screen.generation, revision = screen.revision},
    operation = {kind = "close"},
})

Close requires the exact current revision. Activate can tolerate unrelated slot changes when every named target and guard still matches.

Recover from changed evidence

If the result is gui_precondition_failed, screen_changed, or screen_closed, do not retry the old reference. Take a new snapshot and decide whether the goal still applies.

For a changing solver, subscribe to gui.changed after the current revision. See events and the Experiment Table source.