App.GTUI

constructor({ host, theme = {…} } = {…}) constructor

Create a runtime for a host.

Returns GTUI — configured runtime

Throws — {TypeError} if host is missing

dispatch(message) method

Deliver one message immediately to the running application.

message object

application message

Returns void

run(app) method

Start an application and return its eventual completion result.

Returns Promise<{reason: string, code: number}> — completion promise; rejects on runtime failure

Throws — {Error} if already running; TypeError if required callbacks are absent

stop(reason = "stop", code = 0) method

Stop the application, canceling tasks and timers and restoring the host.

[reason="stop"] string

completion reason

[code=0] number

completion code

Returns void

after(ms, message) method

Describe delayed message delivery.

ms number

delay in milliseconds

message object

message to dispatch

Returns object — frozen timer effect

cancel(key) method

Describe cancellation of a keyed task.

key *

task identity

Returns object — frozen cancellation effect

copy(text, id) method

Request host-mediated text copying.

text string

text to copy

[id] *

optional correlation identifier

Returns object — frozen copy effect

notify(text) method

Request a host notification.

text string

notification text

Returns object — frozen notification effect

open(url) method

Request host-mediated URL opening.

url string

URL to open

Returns object — frozen open effect

quit(code = 0) method

Request application shutdown.

[code=0] number

completion status code

Returns object — frozen quit effect

refresh() method

Request a render without changing the model.

Returns object — frozen refresh effect

task(key, run) method

Describe an abortable asynchronous task.

key *

task identity

run Function

async task receiving signal and send

Returns object — frozen task effect

theme(tokens) method

Replace theme tokens at runtime.

tokens object

theme token mapping

Returns object — frozen theme effect

copyDone(payload) method

Create a completed-copy event.

payload object

event fields

Returns object — frozen copy-done event

focus(payload) method

Create a focus event.

payload object

event fields

Returns object — frozen focus event

inputChange(payload) method

Create an input-change event.

payload object

event fields

Returns object — frozen input-change event

inputSubmit(payload) method

Create an input-submit event.

payload object

event fields

Returns object — frozen input-submit event

key(payload) method

Create a key event.

payload object

event fields

Returns object — frozen key event

linkOpen(payload) method

Create a link-open event.

payload object

event fields

Returns object — frozen link-open event

menuCancel(payload = {…}) method

Create a menu-cancel event.

[payload={}] object

event fields

Returns object — frozen menu-cancel event

menuSelect(payload) method

Create a menu-selection event.

payload object

event fields

Returns object — frozen menu-selection event

paste(payload) method

Create a paste event.

payload object

event fields

Returns object — frozen paste event

pointer(payload) method

Create a pointer event.

payload object

event fields

Returns object — frozen pointer event

resize(payload) method

Create a resize event.

payload object

event fields

Returns object — frozen resize event

selectionCopy(payload) method

Create a selection-copy event.

payload object

event fields

Returns object — frozen selection-copy event

taskDone(payload) method

Create a completed-task event.

payload object

event fields

Returns object — frozen task-done event

taskFailed(payload) method

Create a failed-task event.

payload object

event fields

Returns object — frozen task-failed event

memory(...) method

Create a memory host for deterministic application tests.

terminal(...) method

Create a terminal host for interactive execution.

effects property

flush() method

Finish pending host output; memory hosts have nothing to flush.

Returns void

restoreCount property

send(message) method

Send a host input message to the mounted application.

message object

input message

Returns void

snapshot() method

Return the current rendered scene in semantic, testable form.

Returns object — scene snapshot with current dimensions

button(props = {…}, label = "") method

Create a button node; activation emits action.select {id, action}. pressed styles an on toggle and tone adds a role.

[props={}] object

button properties

[label=""] *

label converted to a string

Returns object — frozen button node

column(...) method

Create an immutable vertical container.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen column node

feed(props = {…}) method

Create an immutable feed control.

[props={}] object

feed properties

Returns object — frozen feed node

footer(props = {…}, items = []) method

Build a one-line footer of app-pushed notification items, aligned start/end; tight rows drop lowest priority first. Empty items yield null.

[props={}] object

row properties

[items=[] Array<object>

] items with text and optional role, priority, align, action

Returns object|null — frozen footer row, or null when empty

grid(...) method

Create an immutable grid container.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen grid node

input(props = {…}) method

Create an immutable controlled text input. The value remains application-owned. mask: true displays one bullet per codepoint; a non-empty string requests a one-cell mask glyph (invalid glyphs use a bullet). Masking preserves the actual value and UTF-16 caret/selection offsets, hides completions, disables Copy, and omits the actual value from JSON and ordinary debug inspection. Masking is presentation, not encryption: direct node.value access still returns the actual value; input.change/input.submit carry it to the owner.

[props={}] object

Input properties including optional value, mask, caret, selection, focus, and placeholder. Properties are shallow-copied; referenced objects are retained, not mutated.

Returns object — Frozen input node; construction has no side effects and is retry-safe.

Throws — {Error} Propagates property-access or mask string processing errors.

menu(props = {…}) method

Create an immutable menu control. searchItems optionally supplies a broader item list used only while the type-to-filter query is nonempty; the empty query displays items. Filtering does not mutate either list. Action items with alwaysVisible:true remain during filtering. Set labelOverflow:"clip-middle" for single-row labels preserving both ends, "clip-end" for single-row labels clipped at the tail; the default wraps. menu.change reports {id,item,query,reason}, with reason "filter" for query edits and "navigation" for arrow moves.

[props={}] object

menu properties

Returns object — frozen menu node

overlay(...) method

Create an immutable overlay container. passive: true draws its last child above anchorAction in the first child's canvas without reserving layout rows or capturing input; position: "above-right" aligns its right edge.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen overlay node

panel(...) method

Create an immutable bordered panel.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen panel node

row(...) method

Create an immutable horizontal container.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen row node

scroll(...) method

Create an immutable scroll container. Keyboard scroll.change events carry source:"keyboard" and repaint immediately; wheel paints remain coalesced.

[props={}] object

node properties

[children=[] Array|*

] child nodes

Returns object — frozen scroll node

table(props = {…}, rows = []) method

Create an immutable table with frozen rows and cells.

[props={}] object

table properties

[rows=[] object[]

] rows; each row's cells are copied and frozen

Returns object — frozen table node

text(props = {…}, content = "") method

Create immutable text content.

[props={}] object

text-node properties

[content=""] *

text content

Returns object — frozen text node

toolbar(...) method

Create a horizontal toolbar container with host-owned roving focus. Children use {id, focus, gap?, align?: "end"}; while focused, navigation keys move focus and Enter/Space activate; other keys bubble.

[props={}] object

toolbar properties

[children=[] Array|*

] button children

Returns object — frozen toolbar node