Documentation

C ABI reference

Every function in aster.h at ABI 1.4, one entry each, with ownership, threading and errors. Each example was compiled and run against the runtime.

This page documents every function in aster.h at ABI 1.4: 25 functions, one entry each. It is derived from the header and from the runtime source (native/runtime/src/lib.rs) at aster-ui f19b91bcd, and every example below was compiled and run against a build of that source on Linux (see "How this page was checked"). Where something could not be confirmed from the source or by running it, the entry says not verified.

The runtime is a native library (libaster_runtime.so on Linux, aster_runtime.dll on Windows) plus the aster command-line tool. Your program keeps its own state, describes the screen as JSON, and receives user actions as JSON events.

The model in one screen

C
/* The setup every example on this page shares. */
#include "aster.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* A small app: a heading, a text field bound to state key "name", and a button that fires the action "add". */
static const char *COUNTER =
    "{\"title\":\"Counter\",\"width\":360,\"height\":240,"
    "\"state\":{\"count\":0,\"name\":\"\"},"
    "\"view\":{\"type\":\"col\",\"gap\":4,\"pad\":6,\"children\":["
    "{\"type\":\"heading\",\"title\":\"Counter\"},"
    "{\"type\":\"text_field\",\"key\":\"name\",\"placeholder\":\"Your name\"},"
    "{\"type\":\"button\",\"text\":\"Add one\",\"action\":\"add\"}]}}";
  1. aster_app_new creates an app from a JSON descriptor. The calling thread becomes the app's UI thread.
  2. You describe the screen with aster_app_set_view and your data with aster_app_set_state.
  3. You register one event callback with aster_app_on_event. It runs on the UI thread when the user clicks, types, flips a switch and so on.
  4. Either aster_app_run opens a window and blocks until it closes, or you drive the app headless (aster_app_click, aster_app_shot, aster_app_tree, ...), which is what tests, recorders and LLM agents use.
  5. aster_app_free releases the app.

Conventions that apply to every function

  • Strings are UTF-8 and NUL-terminated. A NULL string argument fails with an error naming the argument ("label is NULL"). A string that is not valid UTF-8 fails the same way.
  • Return values. Functions that return int give 0 on success and -1 on failure, except aster_app_animating (see its entry). Functions that return a pointer give NULL on failure.
  • Errors. On failure the function stores a message you read with aster_last_error() on the same thread. The message ends with a stable code and a help link, for example ... [aster error wrong-thread: https://barnyardgreens.farm/aster/errors/wrong-thread]. The codes in this build are: wrong-thread, bad-json, unknown-theme, click-target-missing, duplicate-key, state-loop, already-ran, wrong-time, no-display, image-load, stale-handle, bad-argument, internal, other. The view layer adds its own, for example unknown-type (seen in the tree text below). The code is derived from the message text (error_code in lib.rs), so treat it as a hint and the message as the source of truth. Whether the help pages at that link are live was not checked.
  • Panics never cross the boundary. Every entry point catches panics and turns them into a -1/NULL with code internal.
  • Thread rules are summarised in the table below and repeated in each entry.
FunctionThread
aster_abi_version, aster_runtime_version, aster_last_error, aster_freeany
aster_app_set_view, aster_app_set_state, aster_app_set_themeany, queued
every other aster_app_*the UI thread only (the one that called aster_app_new)

"UI thread only" means: called from another thread the function fails with code wrong-thread and changes nothing. aster_app_free from another thread frees nothing.

Lifetime and ownership at a glance

  • The AsterApp * is valid from aster_app_new until aster_app_free. Free it on the UI thread, after every other thread has stopped using it.
  • The runtime never keeps your string arguments past the call. It copies what it needs.
  • Strings the runtime returns (aster_app_tree, aster_app_state) are yours: release them with aster_free, never with free.
  • aster_runtime_version and aster_last_error return pointers you do not free. The first is static. The second belongs to the calling thread and is overwritten by the next failing call on that thread.
  • The event_json string given to your callback is valid only during the callback. Copy it if you need it later.

Library functions

aster_abi_version

C
uint32_t aster_abi_version(void);

Returns the ABI the loaded library implements as major << 16 | minor. This build returns 0x00010004 (1.4). Majors break, minors only add functions, so check major == ASTER_ABI_MAJOR and the minor against the first version that has the function you need (the header marks each addition: 1.1, 1.2, 1.4).

  • Ownership: returns a value, nothing to free.
  • Threading: any thread.
  • Errors: cannot fail.
C
/* example: aster_abi_version */
static void example_aster_abi_version(void) {
    uint32_t abi = aster_abi_version();
    if ((abi >> 16) != ASTER_ABI_MAJOR) { printf("incompatible runtime\n"); return; }
    printf("ABI %u.%u\n", abi >> 16, abi & 0xffff);
}

aster_runtime_version

C
const char *aster_runtime_version(void);

Returns the runtime's product version string, for example "0.1.0".

  • Ownership: static storage; do not free.
  • Threading: any thread.
  • Errors: cannot fail.
C
/* example: aster_runtime_version */
static void example_aster_runtime_version(void) {
    printf("Aster Runtime %s\n", aster_runtime_version());
}

aster_last_error

C
const char *aster_last_error(void);

Returns the message of the last failure on the calling thread, or "" when this thread has not had one yet.

  • Ownership: the pointer belongs to the runtime. It stays valid until the next failing call on the same thread, which replaces the message. Copy the text if you need it longer.
  • Threading: any thread; the message is per thread, so read it on the thread that made the failing call. A failure on a worker thread (for example a setter given bad JSON) is not visible on the UI thread.
  • Errors: cannot fail.
  • Note: a successful call does not clear the message (checked in the source and by running it: after a failed call, a later successful aster_app_set_state left the old text in place). Test the return value of the call, not aster_last_error().
C
/* example: aster_last_error */
static void example_aster_last_error(void) {
    AsterApp *app = aster_app_new("{\"theme\":\"plaid\"}");   /* no such theme */
    if (!app) printf("new failed: %s\n", aster_last_error());
}

aster_free

C
void aster_free(char *s);

Releases a string returned by aster_app_tree or aster_app_state. NULL is accepted and ignored.

  • Ownership: takes back a runtime-allocated string. Use this and nothing else: the string comes from the runtime's allocator, so free() is wrong. Freeing the same pointer twice, or a pointer the runtime did not return, is undefined behavior.
  • Threading: any thread (the source does not check the thread). Not otherwise synchronised: do not free one pointer from two threads.
  • Errors: cannot fail.
C
/* example: aster_free */
static void example_aster_free(void) {
    AsterApp *app = aster_app_new(COUNTER);
    char *tree = aster_app_tree(app);
    if (tree) printf("%zu bytes of tree\n", strlen(tree));
    aster_free(tree);              /* never free(tree) */
    aster_free(NULL);              /* fine */
    aster_app_free(app);
}

App lifecycle

aster_app_new

C
AsterApp *aster_app_new(const char *desc_json);

Creates an app. desc_json may be NULL or "" (an empty app with an empty view). Otherwise it is a JSON object with these keys, all optional:

keymeaningdefault
titlewindow title"Aster"
width, heightlogical pixels, clamped to 64..16384800 x 600
scaledevice scale, clamped to 0.25..81
themeone of the theme names in the headerdark
clock"auto" or "manual" (headless animation clock, see aster_app_set_clock)"auto"
stateinitial state, a JSON object{}
viewinitial view, a JSON object (or array)an empty array
gpu"auto", "on" or "off": window GPU mode. Not mentioned in aster.h; read from the source. The ASTER_GPU environment variable overrides it. Headless calls never use the GPU."auto"
  • Ownership: returns a new app that you must release with aster_app_free. NULL on failure.
  • Threading: any thread may create an app; the calling thread becomes the app's UI thread for life. Keep every non-setter call on that thread.
  • Errors: bad-json for malformed JSON, unknown-theme for a bad theme name, bad-argument for non-UTF-8, other for an unknown gpu value. It does not need a display: creation is headless.
  • Note: a descriptor whose view is valid JSON but uses an unknown node type is accepted (checked): the app is created and the unknown node draws as a visible placeholder, [aster: unknown type "nonesuch" · aster error unknown-type]. Width and height below 64 are clamped (a 10x10 request gave a 64x64 frame, checked).
C
/* example: aster_app_new */
static void example_aster_app_new(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (!app) { printf("new failed: %s\n", aster_last_error()); return; }
    AsterApp *empty = aster_app_new(NULL);          /* legal: an empty app */
    aster_app_free(empty);
    aster_app_free(app);
}

aster_app_free

C
void aster_app_free(AsterApp *app);

Destroys an app and releases the engine it owned. Queued updates that were never applied are dropped. NULL is accepted.

  • Ownership: ends the app's life. After this the pointer is stale: setters given it fail with stale-handle (they look it up in a registry and never touch the freed memory), and the address is never reused for a later app. The runtime keeps a small allocation (96 bytes on x64) per freed app for the life of the process to guarantee that.
  • Threading: UI thread only, after every other thread has stopped calling functions with this pointer and none of those calls is still in progress. Called off the UI thread it frees nothing and sets wrong-thread (checked), so the UI thread can still free it later.
  • Errors: (reported through aster_last_error, no return value) wrong-thread as above. wrong-time when a call on the app is still in progress on the UI thread, for example freeing from inside the event callback while aster_app_click, aster_app_type or aster_app_run is running: it frees nothing, so free after that call returns.
  • Caution: only the three setters are protected against a freed pointer. Calling any other function, or aster_app_free a second time, with an already freed pointer is not covered by the header's guarantees: treat a double free as undefined behavior. Not verified by running it.
C
/* example: aster_app_free */
static void example_aster_app_free(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_free(app);
    /* A setter racing with the free is safe: it fails with a stale-handle error. */
    if (aster_app_set_state(app, "{\"count\":1}") != 0)
        printf("after free: %s\n", aster_last_error());
}

Updating the app (any thread)

These three are queued, not applied immediately. They check their argument (bad JSON or an unknown theme fails), queue the update, and wake the window. The UI thread applies the queue in the run loop before the next frame, at the start of its next call on the app, and when the event callback returns. A queued update is either applied or dropped (when the window has closed or at aster_app_free); a setter never fails because the window closed.

aster_app_set_view

C
int aster_app_set_view(const AsterApp *app, const char *view_json);

Replaces the whole view. The view is a JSON node such as {"type":"col","children":[...]}; the node types are listed in the runtime's docs/view-*.md files and demonstrated by native/runtime/samples/*.json. Returns 0 or -1.

  • Ownership: the string is copied (parsed) during the call.
  • Threading: any thread, including from inside the event callback. Does not touch the app on the calling thread.
  • Errors: bad-json when the text is not JSON, bad-argument for NULL, stale-handle for a freed or never-issued pointer. Only JSON syntax is checked on the calling thread. A well-formed JSON view with a wrong node type is accepted (returns 0, checked by running it): the unknown node draws as a placeholder text [aster: unknown type "nonesuch" · aster error unknown-type] in the tree and the frame. So a typo in a node type does not fail; look at the tree or a screenshot.
  • Note: the whole view is replaced, so send the complete new view, not a patch. Use state plus bound keys (a text_field with "key") for values that change often.
C
/* example: aster_app_set_view */
static void example_aster_app_set_view(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_set_view(app,
            "{\"type\":\"col\",\"pad\":6,\"children\":[{\"type\":\"text\",\"text\":\"Replaced\"}]}") != 0)
        printf("set_view failed: %s\n", aster_last_error());
    char *tree = aster_app_tree(app);       /* applies the queued view first */
    printf("%s\n", strstr(tree, "Replaced") ? "view replaced" : "view NOT replaced");
    aster_free(tree);
    aster_app_free(app);
}

aster_app_set_state

C
int aster_app_set_state(const AsterApp *app, const char *state_json);

Merges the keys of a JSON object into the app state. Keys you do not mention keep their values. Returns 0 or -1.

  • Ownership: copied during the call.
  • Threading: any thread; queued. If the same key is queued twice before the UI thread drains, the last value wins, so an unattended queue never grows beyond the size of the state.
  • Errors: bad-json for bad JSON or when the value is not an object (state must be a JSON object), bad-argument for NULL, stale-handle for a freed pointer.
  • Echo rule: state you set yourself is not reported back to your callback as a change event.
  • Key naming: aster_app_state and event state objects leave out keys that start with __ or ~ and keys that contain a . (those are runtime bookkeeping such as field.focused). Do not put dots in your own state keys if you want to read them back.
  • Types: JSON integers become integers, other numbers become floats, strings become text, null becomes the empty string, arrays and objects become lists and records.
C
/* example: aster_app_set_state */
static void example_aster_app_set_state(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_set_state(app, "{\"count\":7}");
    char *st = aster_app_state(app);        /* applies the queue first */
    printf("%s\n", st);
    aster_free(st);
    aster_app_free(app);
}

aster_app_set_theme

C
int aster_app_set_theme(const AsterApp *app, const char *theme);   /* ABI 1.1 */

Switches the theme by name: dark (default), light, mission_dark, mission_light, mission_dusk, paper_dark, paper_light, high_contrast_dark, high_contrast_light. The source also accepts a few spellings (case-insensitive, - and space as _, and the aliases mission, dusk, paper, contrast, high_contrast). Returns 0 or -1.

  • Ownership: copied during the call.
  • Threading: any thread; queued like the other setters.
  • Errors: unknown-theme for a name not in the list, bad-argument for NULL, stale-handle for a freed pointer.
C
/* example: aster_app_set_theme */
static void example_aster_app_set_theme(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_set_theme(app, "paper_light") != 0) printf("%s\n", aster_last_error());
    if (aster_app_set_theme(app, "plaid") != 0)       printf("expected: %s\n", aster_last_error());
    aster_app_free(app);
}

Events

aster_app_on_event

C
typedef void (*AsterEventFn)(void *user, const char *event_json);
int aster_app_on_event(const AsterApp *app, AsterEventFn cb, void *user);

Sets, replaces or (with cb == NULL) clears the event callback. One callback per app. user is passed back unchanged.

The callback runs on the UI thread, inside the call that produced the event (aster_app_click, aster_app_type, the input functions, aster_app_run's loop). event_json is valid only during the call:

JSON
{"type":"action","action":"add","key":"","state":{"count":0,"name":""},"selection":{}}
  • type: "action": a button, menu item, command palette entry or keyboard shortcut fired. action names it (the "action" of the node that fired). ABI 1.0 sent "click" here.
  • type: "change": the user changed state the host has not seen (typing, a switch, a tab, a slider). Sent once per real change. ABI 1.1.
  • state: the current host-visible state after that event.
  • selection: caret and selection of every text input, as character indices: {"name":{"start":2,"end":5,"caret":5}}. ABI 1.1.

Inside the callback you answer with aster_app_set_view / aster_app_set_state / aster_app_set_theme. They are queued and land in the same frame as the click, when the callback returns.

  • Ownership: the runtime stores cb and user and never frees user. The pointer must stay valid until you clear the callback or free the app. Your callback must not free the app (it fails with wrong-time).
  • Threading: UI thread only (wrong-thread otherwise). The callback is only ever invoked on the UI thread.
  • Errors: wrong-thread, bad-argument for a NULL app.
  • Panics: a panic inside the runtime while it calls you is caught; the callback itself is C, so it must not unwind or longjmp out.
C
/* example: aster_app_on_event */
typedef struct { int adds; } Counter;

static void on_event(void *user, const char *event_json) {
    Counter *c = (Counter *)user;
    if (strstr(event_json, "\"action\":\"add\"")) c->adds++;
}

static void example_aster_app_on_event(void) {
    Counter c = {0};
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_on_event(app, on_event, &c);
    aster_app_click(app, "Add one");
    aster_app_click(app, "Add one");
    printf("adds = %d\n", c.adds);
    aster_app_on_event(app, NULL, NULL);          /* clear before c goes out of scope */
    aster_app_free(app);
}

Running a window

aster_app_run

C
int aster_app_run(const AsterApp *app);

Opens the window and blocks until the user closes it. Returns 0 on a normal close, -1 on failure.

  • Ownership: while it runs, the app belongs to the loop. When it returns, the window and its engine are gone. Afterwards only aster_app_free is useful; the headless functions fail with "the app has already run and closed".
  • Threading: UI thread only, and the window's loop runs on that thread, so it blocks there. Other threads keep using the three setters, which wake the window. Your callback runs inside the loop.
  • Errors: already-ran if the app has run before (once per app), no-display when no display can be opened (checked on Linux with no DISPLAY/WAYLAND_DISPLAY: the message names the missing variables), wrong-thread. A failed run still consumes the app (checked): the second aster_app_run gave already-ran and aster_app_state gave "the app has already run and closed". Create a new app to retry, for example after fixing the display. While the window is running, aster_app_state, aster_app_tree, aster_app_shot and the other headless calls fail with wrong-time ("not available while the window is running"); use the state field of the events instead.
  • GPU: a window installs the GPU frame accelerator when one is available and falls back to CPU drawing otherwise (source comment). The headless functions never use it, so shots and pixels are always the CPU renderer's bytes.
  • Not run here: opening a window needs a display. This page's examples ran headless; the aster_app_run example was compiled but not run.
C
/* example: aster_app_run */
static void on_action(void *user, const char *event_json) {
    AsterApp *app = (AsterApp *)user;
    if (strstr(event_json, "\"action\":\"add\""))
        aster_app_set_state(app, "{\"count\":1}");     /* a setter may be called from the callback */
}

static int example_aster_app_run(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (!app) return 1;
    aster_app_on_event(app, on_action, app);
    int rc = aster_app_run(app);                       /* blocks until the window closes */
    if (rc != 0) printf("run failed: %s\n", aster_last_error());
    aster_app_free(app);
    return rc;
}

Headless driving

Everything in this section is UI thread only, fails with wrong-time while a window is running, and can run with no display at all. In the default clock mode each call leaves the app settled (animations finished) so a screenshot never shows a half-open dialog. With the manual clock (see aster_app_set_clock) calls only start motion.

aster_app_click

C
int aster_app_click(const AsterApp *app, const char *label);

Clicks the element whose label (or key) is label, settles, and fires the event callback (an action event, then a change event if state changed). Returns 0 or -1.

  • Ownership: label is only read during the call.
  • Threading: UI thread only.
  • Errors: click-target-missing when no interactive element has that label ("no interactive target"), wrong-thread, wrong-time, bad-argument. The callback is invoked synchronously, so a callback that calls aster_app_free gets wrong-time.
C
/* example: aster_app_click */
static void example_aster_app_click(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_click(app, "Add one") != 0) printf("%s\n", aster_last_error());
    if (aster_app_click(app, "Nonexistent") != 0) printf("expected: %s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_type

C
int aster_app_type(const AsterApp *app, const char *text);   /* ABI 1.1 */

Types text into the focused element. Click or focus an input first. After typing it settles (default clock) and reports the state change through the callback. Returns 0 or -1.

  • Ownership: text is read during the call.
  • Threading: UI thread only.
  • Errors: wrong-thread, wrong-time, bad-argument. With nothing focused the call returns 0 and changes nothing (checked): it does not tell you the text went nowhere, so focus first (aster_app_focus or a click).
C
/* example: aster_app_type */
static void example_aster_app_type(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_focus(app, "name");
    aster_app_type(app, "Ada");
    char *st = aster_app_state(app);
    printf("%s\n", st);                      /* the name key now reads "Ada" */
    aster_free(st);
    aster_app_free(app);
}

aster_app_shot

C
int aster_app_shot(const AsterApp *app, const char *png_path);

Renders the current frame and writes it as a PNG file. This is the call to use when you want to look at what the app draws. Returns 0 or -1.

  • Ownership: png_path is read during the call; the file is written by the runtime. The image is device pixels (logical size x scale).
  • Threading: UI thread only.
  • Errors: wrong-thread, wrong-time, bad-argument, and an other error when the file cannot be written (the message carries the OS error). Writing twice to the same path succeeds and overwrites (checked). A directory that cannot be written gives an other error whose message carries the OS error.
C
/* example: aster_app_shot */
static void example_aster_app_shot(const char *path) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_shot(app, path) != 0) printf("%s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_tree

C
char *aster_app_tree(const AsterApp *app);

Returns the semantic tree as text: every labelled element with its role and rectangle. NULL on failure.

  • Ownership: a new string you must release with aster_free.
  • Threading: UI thread only.
  • Errors: wrong-thread, wrong-time.
  • Note: the text format is for people and test assertions (search it with strstr); it is not documented as a stable machine format.
C
/* example: aster_app_tree */
static void example_aster_app_tree(void) {
    AsterApp *app = aster_app_new(COUNTER);
    char *tree = aster_app_tree(app);
    if (tree) printf("%s", tree);
    aster_free(tree);
    aster_app_free(app);
}

aster_app_state

C
char *aster_app_state(const AsterApp *app);

Returns the current host-visible state as a JSON object. NULL on failure.

  • Ownership: a new string; release with aster_free.
  • Threading: UI thread only. Not available while the window runs (wrong-time).
  • Errors: wrong-thread, wrong-time.
  • Note: runtime-internal keys (starting __ or ~, or containing .) are left out.
C
/* example: aster_app_state */
static void example_aster_app_state(void) {
    AsterApp *app = aster_app_new(COUNTER);
    char *st = aster_app_state(app);
    printf("%s\n", st);
    aster_free(st);
    aster_app_free(app);
}

Headless clock (ABI 1.2)

Offline rendering injects the animation clock; it never reads the wall clock. That is what makes a recorded video frame-exact.

aster_app_set_clock

C
int aster_app_set_clock(const AsterApp *app, int manual);   /* 0 auto, 1 manual */

Chooses the headless clock. 0 (auto, the default): every headless call leaves the app settled. Non-zero (manual): click, type, set_state, set_view and set_theme only start motion; aster_app_advance plays it. You can also choose it at creation with "clock":"manual". Returns 0 or -1.

  • Threading: UI thread only.
  • Errors: wrong-thread, bad-argument (NULL app).
C
/* example: aster_app_set_clock */
static void example_aster_app_set_clock(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_set_clock(app, 1);          /* manual */
    aster_app_set_clock(app, 0);          /* back to auto */
    aster_app_free(app);
}

aster_app_advance

C
int aster_app_advance(const AsterApp *app, double ms);

Moves the animation clock forward by ms milliseconds (fractions carry to the next call, so 33.33 ms steps stay exact) and renders that frame. Works in either clock mode; in manual mode it is the only thing that plays motion. Same calls give the same pixels. Returns 0 or -1.

  • Threading: UI thread only.
  • Errors: fails when ms is negative, NaN or infinite ("ms must be a finite number of milliseconds, 0 or more"); a single call advances at most one hour (3,600,000 ms; longer values are capped, not rejected). Also wrong-thread, wrong-time.
C
/* example: aster_app_advance */
static void example_aster_app_advance(void) {
    AsterApp *app = aster_app_new("{\"clock\":\"manual\",\"width\":320,\"height\":200,"
                                  "\"view\":{\"type\":\"text\",\"text\":\"Hi\"}}");
    for (int i = 0; i < 3; i++) {
        if (aster_app_advance(app, 1000.0 / 60.0) != 0) { printf("%s\n", aster_last_error()); break; }
        /* aster_app_shot(app, "frame.png") here to capture each frame */
    }
    aster_app_free(app);
}

aster_app_animating

C
int aster_app_animating(const AsterApp *app);

Returns 1 when more time would change the picture (a transition is running or a timer is pending), 0 when the app is at rest, -1 on error. An endless motion such as a spinner counts as animating.

  • Threading: UI thread only.
  • Errors: -1 with wrong-thread or wrong-time. This is the one int function where -1 is not the only non-zero result: test == 1, not != 0.
C
/* example: aster_app_animating */
static void example_aster_app_animating(void) {
    AsterApp *app = aster_app_new(COUNTER);
    int a = aster_app_animating(app);
    if (a < 0) printf("%s\n", aster_last_error());
    else printf("animating: %d\n", a);
    aster_app_free(app);
}

Headless input and pixels (ABI 1.4)

What a test, a recorder or another toolkit's host uses to drive the app like a person and read the frame back without a PNG. Coordinates are logical pixels (the units of the view). Pixels are device pixels (logical size x scale). Each input call settles like aster_app_click unless the clock is manual, and reports state changes through the callback. All of them are UI thread only.

aster_app_pointer

C
#define ASTER_POINTER_MOVE  0
#define ASTER_POINTER_DOWN  1
#define ASTER_POINTER_UP    2
#define ASTER_POINTER_LEAVE 3
#define ASTER_POINTER_CLICK 4
int aster_app_pointer(const AsterApp *app, int kind, double x, double y);

Moves, presses, releases, leaves the window, or does a whole click (move, press, release) at logical (x, y). For ASTER_POINTER_LEAVE the coordinates are ignored but must be finite. Returns 0 or -1.

  • Errors: an unknown kind fails (message lists 0 to 4), non-finite x or y fails, plus wrong-thread, wrong-time.
  • Use: hover effects (MOVE), drags (DOWN, MOVE, UP), and clicking by position when an element has no label.
C
/* example: aster_app_pointer */
static void example_aster_app_pointer(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_pointer(app, ASTER_POINTER_MOVE, 40, 60);
    aster_app_pointer(app, ASTER_POINTER_CLICK, 40, 60);
    aster_app_pointer(app, ASTER_POINTER_LEAVE, 0, 0);
    if (aster_app_pointer(app, 99, 0, 0) != 0) printf("expected: %s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_wheel

C
int aster_app_wheel(const AsterApp *app, double x, double y, double dy);

One wheel step at (x, y). dy > 0 scrolls down (content moves up); a notch is 40 logical pixels. Returns 0 or -1.

  • Errors: non-finite x, y or dy fails; wrong-thread, wrong-time.
C
/* example: aster_app_wheel */
static void example_aster_app_wheel(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_wheel(app, 100, 100, 40) != 0) printf("%s\n", aster_last_error());   /* one notch down */
    aster_app_free(app);
}

aster_app_key

C
int aster_app_key(const AsterApp *app, const char *chord);

Presses and releases a key chord on the focused element or as an app-wide shortcut: "enter", "ctrl+s", "shift+tab", "a". Returns 0 or -1.

  • Errors: an unrecognised chord fails (unknown key chord "..."); wrong-thread, wrong-time, bad-argument. Checked: enter, ctrl+s, shift+tab, a, escape, tab, space, up, ctrl+shift+z, Ctrl+S (case-insensitive) and cmd+s were accepted; f5 and page_down were rejected. The full grammar is not in the header, so treat a -1 as "chord not supported" rather than a bug in your call.
C
/* example: aster_app_key */
static void example_aster_app_key(void) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_focus(app, "add");
    if (aster_app_key(app, "enter") != 0) printf("%s\n", aster_last_error());   /* activates the focused button */
    if (aster_app_key(app, "ctrl+nope") != 0) printf("expected: %s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_focus

C
int aster_app_focus(const AsterApp *app, const char *id);

Focuses the element whose id (its key or id in the view) is id. Returns 0 or -1.

  • Errors: an id that does not exist fails; wrong-thread, wrong-time, bad-argument.
C
/* example: aster_app_focus */
static void example_aster_app_focus(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_focus(app, "name") != 0) printf("%s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_resize

C
int aster_app_resize(const AsterApp *app, uint32_t width, uint32_t height, double scale);

Re-renders at a new logical size and output scale, like a window resize or a display DPI change. width and height must be 64..16384 and scale 0.25..8, otherwise it fails and changes nothing. Returns 0 or -1.

  • Errors: out of range (message: "resize wants 64..16384 logical px each and a scale of 0.25..8"); wrong-thread, wrong-time.
  • Note: the header says only "0.25..8" for scale; the 64..16384 limits come from the source.
C
/* example: aster_app_resize */
static void example_aster_app_resize(void) {
    AsterApp *app = aster_app_new(COUNTER);
    if (aster_app_resize(app, 400, 300, 1.5) != 0) printf("%s\n", aster_last_error());
    if (aster_app_resize(app, 1, 1, 1.0) != 0)     printf("expected: %s\n", aster_last_error());
    aster_app_free(app);
}

aster_app_pixels

C
int aster_app_pixels(const AsterApp *app, uint8_t *rgba, size_t capacity,
                     uint32_t *width, uint32_t *height);

Reads the current frame back as straight (non-premultiplied) RGBA, 4 bytes per device pixel, rows top to bottom. width and height may be NULL. With rgba == NULL it only reports the size, so the usual pattern is two calls: ask for the size, allocate width * height * 4 bytes, then call again. If capacity < width * height * 4 it fails and copies nothing. Returns 0 or -1.

  • Ownership: you own rgba. The runtime writes into it during the call only and never keeps it.
  • Threading: UI thread only.
  • Errors: a too-small buffer (message states the bytes needed), wrong-thread, wrong-time.
  • Size: device pixels, so a 400 x 300 view at scale 1.5 is 600 x 450.
C
/* example: aster_app_pixels */
static void example_aster_app_pixels(void) {
    AsterApp *app = aster_app_new(COUNTER);
    uint32_t w = 0, h = 0;
    if (aster_app_pixels(app, NULL, 0, &w, &h) != 0) { printf("%s\n", aster_last_error()); return; }
    size_t n = (size_t)w * h * 4;
    uint8_t *rgba = (uint8_t *)malloc(n);
    if (rgba && aster_app_pixels(app, rgba, n, &w, &h) == 0)
        printf("%ux%u, first pixel %02x%02x%02x%02x\n", w, h, rgba[0], rgba[1], rgba[2], rgba[3]);
    free(rgba);
    aster_app_free(app);
}

Putting it together: a headless session

The whole loop an agent or a test uses: create, drive, look, free.

C
/* example: session */
static void on_session_event(void *user, const char *event_json) {
    AsterApp *app = (AsterApp *)user;
    if (strstr(event_json, "\"action\":\"add\"")) {
        static int n = 0;
        char state[64];
        snprintf(state, sizeof state, "{\"count\":%d}", ++n);
        aster_app_set_state(app, state);        /* answer the click */
    }
}

static void example_session(const char *png_path) {
    AsterApp *app = aster_app_new(COUNTER);
    aster_app_on_event(app, on_session_event, app);
    aster_app_click(app, "Add one");
    aster_app_click(app, "Add one");
    char *st = aster_app_state(app);
    printf("%s\n", st);
    aster_free(st);
    aster_app_shot(app, png_path);
    aster_app_free(app);
}

Linking

  • Linux: link against libaster_runtime.so (built as the cdylib of the aster-runtime crate), for example cc -I native/runtime/include prog.c -L <target>/debug -laster_runtime -Wl,-rpath,<target>/debug. This is the command the repo's own tests/smoke.c documents, and the one used to check this page.
  • Windows: the header marks functions __declspec(dllimport), so you link the import library aster_runtime.dll.lib that is written next to aster_runtime.dll and ship the DLL next to your program. The DLL and its import library were cross-built from Linux; linking and running a C program on Windows was not run here.
  • Other languages: any language with a C FFI can call these 25 functions. The strings are plain UTF-8; there are no structs other than the opaque AsterApp.

How this page was checked

Each /* example: ... */ block was extracted from this page's source by a script, compiled together with aster.h (cc -Wall -Wextra, clean) and run on Linux against libaster_runtime.so built from aster-ui main f19b91bcd with Rust 1.98.0 (2026-11-15). The window example (aster_app_run) was compiled but not run, because the build machine has no display. On Windows the runtime was cross-built, not run: its import library is aster_runtime.dll.lib and the DLL exports exactly the 25 functions of aster.h. Still unverified: linking and running a C program on Windows, and whether the error help links are live.