Documentation

C ABI

A small, versioned C interface. Describe the screen as JSON, handle events as JSON, keep your state in your own code.

A settings screen drawn by AsterDrawn by Aster

The Aster Runtime is a shared library with one C header, aster.h (ABI 1.4; the header is MIT-licensed and the runtime ships under the Aster Runtime EULA). Your program keeps its own state and describes the screen as JSON; Aster renders it and calls you back with JSON events. There is nothing to link against except the library, and no Rust toolchain is needed on the consumer side.

Status: pre-1.0, signatures not frozen. The ABI is versioned (ASTER_ABI_MAJOR 1, ASTER_ABI_MINOR 4); check the major version at start-up as the example does.

Licence: the SDK and examples are MIT; the runtime ships under the Aster Runtime EULA. The commands below were run from a source checkout; with prebuilt binaries, use the delivered include and lib directories instead.

What we ran

Built on 2026-11-15 from aster-ui f19b91bcd (ABI 1.4) with Rust 1.98.0 in the project's toolchain image, from native/:

Shell
cd native
cargo build --release -p aster-runtime      # produces libaster_runtime.so and the `aster` CLI

Then compiled the quick-start program with warnings as errors, and ran it:

Shell
cd native/../site/content/snippets/c-abi
cc -Wall -Wextra -Werror -I ../../../../native/runtime/include hello.c \
   -L <target>/release -laster_runtime -Wl,-rpath,<target>/release -o hello
./hello hello-c.png

Output (verbatim, recorded on 2026-11-15 with the runtime built from f19b91bcd):

Output
Aster Runtime 0.1.0, ABI 1.4
event: {"type":"action","action":"add","key":"","state":{},"selection":{}}
event: {"type":"action","action":"add","key":"","state":{},"selection":{}}
ui theme=mission-dark viewport=360x240
  #heading-2 Heading rect=[20, 20, 320, 52.82]
    #text-3 Text label="Counter" rect=[20, 20, 320, 33.88]
    #text-4 Text label="from C" rect=[20, 55.88, 320, 16.94]
  #stat-5 Stat rect=[20, 84.82, 320, 84.40]
    #text-6 Text label="Clicks" rect=[36, 100.82, 288, 14.52]
    #text-7 Text label="2" rect=[36, 119.34, 288, 33.88]
  #add button rect=[20, 181.22, 320, 34] key=9 {focusable focused hovered}
    #text-9 Text label="Add one" rect=[151.63, 189.75, 56.74, 16.94]

OK

The PNG it wrote has SHA-256 a6fc521f280e52fd6ee3dd8797b982871112ba629e91d7edd5722bb9d612e350. The repository's own smoke test (native/runtime/tests/smoke.c) renders the same app through a separate program and produced a byte-identical file (same SHA-256).

The program, annotated

snippets/c-abi/hello.c:

  1. aster_abi_version() returns major << 16 | minor. Refuse to run if the major differs from ASTER_ABI_MAJOR.
  2. aster_app_new(desc_json) creates an app from a descriptor: {"title","width","height","scale","theme","clock","state","view"}. Themes: dark (default), light, mission_dark, mission_light, mission_dusk, paper_dark, paper_light, high_contrast_dark, high_contrast_light.
  3. aster_app_on_event(app, cb, user) registers the callback. Events are JSON: {"type":"action"|"change","action":...,"key":...,"state":{...},"selection":{...}}. They are delivered on the UI thread only.
  4. aster_app_set_view(app, json) replaces the screen; aster_app_set_state merges state; both may be called from any thread, including from inside the callback.
  5. Headless driving, for tests and for tools that need to see the UI: aster_app_click(app, "Label"), aster_app_type, aster_app_shot(app, "out.png"), aster_app_tree(app) (the semantic tree; free with aster_free).
  6. aster_app_run(app) opens a window and blocks until it closes (once per app).
  7. Errors: functions returning int give 0 or -1; pointers give NULL; aster_last_error() explains, per thread.

Threading in one paragraph: the thread that creates the app is the UI thread; the three setters (set_view, set_state, set_theme) may be called from any thread and are queued; everything else must be called on the UI thread or fails with a wrong-thread error and changes nothing. Free the app on the UI thread after other threads have stopped using it. The full contract is the comment at the top of aster.h.

Deterministic animation (ABI 1.2): create the app with "clock":"manual" and call aster_app_advance(app, ms) to play motion frame by frame; the same calls give the same pixels.

No code at all: the aster command-line tool

The same runtime ships a CLI, useful for design review and CI:

Shell
aster doctor                       # runtime and ABI version
aster shot  app.json out.png       # render headless to a PNG
aster tree  app.json               # print the semantic tree (labels, roles, rects)
aster click app.json "Say hi"      # click a label headless, print the resulting tree and event
aster run   app.json               # open a window; events print as JSON lines

snippets/c-abi/app.json is a complete app (a heading, a stat and a button). We ran aster shot app.json hello-json.png (SHA-256 b617f33d78bc1dc94b217795e67b4b32a219de20b73f774cc58d33d43844f64c) and aster click app.json "Say hi", which printed {"type":"action","action":"hi","key":"","state":{},"selection":{}}. The larger sample native/runtime/samples/garden.json renders to the "An app described as JSON" image in the gallery.

Not covered here

This guide covers the supported headless and window paths on Linux. Windows packaging (the Store package that ships the runtime) is described in docs/WINDOWS-STORE.md. The Rust facade and the wasm module are described in getting-started.md and wasm.md.

Every exported function

Generated from native/runtime/include/aster.h at aster-ui f19b91bcd (ABI 1.4, 25 functions).

FunctionReturns (parameters)Note
aster_abi_versionuint32_t (void)major << 16 | minor; check major == ASTER_ABI_MAJOR
aster_runtime_versionconst char * (void)static, do not free
aster_last_errorconst char * (void)this thread's last error, "" when none
aster_freevoid (char *s)free strings returned by aster_app_tree / aster_app_state
aster_app_newAsterApp * (const char *desc_json)
aster_app_freevoid (AsterApp *app)UI thread, after other threads stopped and no call on app is in progress
aster_app_set_viewint (const AsterApp *app, const char *view_json)
aster_app_set_stateint (const AsterApp *app, const char *state_json)merge a JSON object
aster_app_on_eventint (const AsterApp *app, AsterEventFn cb, void *user)
aster_app_runint (const AsterApp *app)opens the window, blocks until closed; once per app
aster_app_clickint (const AsterApp *app, const char *label)
aster_app_shotint (const AsterApp *app, const char *png_path)
aster_app_treechar * (const AsterApp *app)free with aster_free
aster_app_statechar * (const AsterApp *app)free with aster_free
aster_app_typeint (const AsterApp *app, const char *text)type into the focused element (ABI 1.1)
aster_app_set_themeint (const AsterApp *app, const char *theme)
aster_app_set_clockint (const AsterApp *app, int manual)0 auto (default), 1 manual
aster_app_advanceint (const AsterApp *app, double ms)clock += ms (fractions carry), render that frame
aster_app_animatingint (const AsterApp *app)1 motion running or timer pending, 0 at rest, -1 error
aster_app_pointerint (const AsterApp *app, int kind, double x, double y)
aster_app_wheelint (const AsterApp *app, double x, double y, double dy)dy > 0 scrolls down; a notch is 40
aster_app_keyint (const AsterApp *app, const char *chord)"enter", "ctrl+s", "shift+tab", "a": press + release
aster_app_focusint (const AsterApp *app, const char *id)
aster_app_resizeint (const AsterApp *app, uint32_t width, uint32_t height, double scale)logical px, 0.25..8
aster_app_pixelsint (const AsterApp *app, uint8_t *rgba, size_t capacity, uint32_t *width, uint32_t *height)