how the abi is designed
the WHY, the freeze rules, and what is deliberately not exported
mirrored from
window/cpp/abi/README.md, which is the only copy of this text. edits made here are overwritten the next time the site builds
the flat c exports over opaque handles, P1.23, i.e. what a DllCall can reach, plus the event
queue that gets something that happened back to a script without ever calling into it, P1.24
links into neither static lib, it is the dll project that pulls in window.core n window.widgets,
so no c++ type n no exception ever crosses out of here. BUILD.md step 7 is the wiring
the files
| file | what |
|---|---|
window_abi.h | the public c header, the contract, read this one first n read it whole |
abi.h | the inside, the registry, the loose list, the scene lock, the with_* shells |
abi.cpp | the registry, the loose list, the two locks, the dll level calls, the desc, the icon n the item builders |
abi_host.cpp | the host, the three pump entries, the spawned path, the input queries, the tweens |
abi_scene.cpp | the generic control calls, the containers, the overlay |
abi_theme.cpp | the theme tokens |
abi_controls.cpp | create for the concrete controls, n create is the whole of it |
abi_event.cpp | the event queue, the coalescing n the one wake per drain |
abi_contract.cpp | P1.B.4, the layout lock, a static assert over every offset, size n enum value |
window_abi.golden.h | the blessed copy of the header, the AbiGoldenHeader target diffs the real one against it |
window.abi.vcxproj | the dll project, BUILD.md step 7 is what it is set to |
../Makefile | make abi, the mac dylib, same sources, see ## on the mac, P.A.1 |
the shape, in three lines
- every export returns an int32 status n every value comes back through an out pointer, so a wrapper checks one thing per call n a 0 is never ambiguous
- every handle is registered, a stale or foreign one is
gui_err_handlerather than a crash, n a control dying anywhere in a tree drops its own handle on the way out throughset_leaving - a control you make is LOOSE n ours til you add it, the tree owns it after, remove hands it back, n a host only ever BORROWS its root
- one lock over the whole scene, P1.24, taken by
guardedso no export can forget it, which is what lets a spawned window paint on its own thread while the caller drives the same tree
the numbers are free until P1.25 ships, n frozen the moment it does
every enum value in window_abi.h is an ordinal a DllCall hardcodes, so it is api exactly the way
a name is. today nothing consumes it, no script n no wrapper, n gui_btn_* n gui_col_* appear nowhere
outside cpp/, which is why P1.A.3 was allowed to put warning in the MIDDLE of both lists on
2026-09-10, moving gui_btn_danger 3 to 4 n every colour from gui_col_danger on by two, n bump
GUI_ABI_VERSION to 2 rather than bolt the new token on the end
settled 2026-09-10, the renumber STAYS n the question is closed. the enum reads in its semantic order n the wrapper is what a script will spell these through anyway, so the raw ordinal is the wrappers problem n not a callers
that freedom ends with P1.25. the moment the wrapper is out there is a caller with no compiler to
tell, so from then on a new value goes at the END of its list n never inside it, n a reorder is a break
rather than a version bump. abi_contract.cpp is what catches the accident, it does not license the
deliberate one
P1.43 is the first change made under that rule n it reads 3. gui_event_select n gui_event_value
went on the END of the event kinds n click grew an i0 it never filled, so every number a script
already hardcoded still means what it meant n the bump is about the HEADER moving n not about a break
4 is a different shape of change and worth reading before the next one goes in. gui_err_unmade
was appended, which the rule above covers, but gui_control_at and gui_control_parent also stopped
answering a missing handle with a null on a gui_ok, so a status a caller ALREADY READS came back a
different value than it used to. nothing in the layout moved and it is still not a reorder, but a
caller checking only the status now sees a refusal where it saw success, which no amount of appending
can warn anybody about. so the rule has a second half, a value that changes what an existing call
ANSWERS is a bump too, even when the header shape is untouched, and the reason this one was allowed
at all is that no script exists yet to be broken by it, which stops being true the day P1.25 ships
5 is the boring case n it is worth having one on the record, P1.E.4 appended gui_host_minimise,
gui_host_maximise n gui_host_restore beside the gui_host_close that was already there. no enum
moved, no existing call answers differently, n a FUNCTION declaration carries no ordinal at all, there
is no .def n nothing is exported by number, so the placement in the header is a readability call n
never api. what forced the bump is the golden copy, the public header reshaped so window_abi.golden.h
had to be re-blessed n abi_contract.cpp re-pinned in the same pass, which is the machinery working
rather than a break. five places moved n not four, the header, the golden copy, the pin, the impls,
n ahk/Kit/abi.ahks call table plus Kit.ahks AbiVersion, n the suite fails on the last of those
before anything else notices
7 is the mac, P.A.1 appended gui_err_unsupported for the two calls that mean nothing off windows.
the GUI_API and GUI_CALL macros changing under #if defined(_WIN32) is NOT what bumped it, the
windows bytes are identical, the appended code is. no call on windows answers differently. the ahk
side moved with it, Kit.AbiVersion and a Kit.Err.Unsupported line, since the suite counts that
class against gui_err_count
on the mac, P.A.1
make abi in cpp/ builds bin/macos_<cfg>/libwindow.abi.dylib off the same seven sources, and the
xcode project has it as window.abi. only the gui_* exports leave it, -exported_symbol,_gui_*
at link, bc the static libs underneath are default visibility and every c++ symbol would go too
the caller it is for is lua, which owns its loop, so the loop is gui_host_pump then drain
gui_event_next, and nothing else. two calls have no mac meaning and answer gui_err_unsupported
gui_host_spawn, appkit only makes a window on the main thread, so there is no far sidegui_event_set_target, there is no hwnd to post at, and a caller that pumps never needs a wake. if one ever blocks somewhere else the answer is an fd it can wait on, never a callback
everything else is the same surface, the thread split included, a thread bound call off main is
gui_err_thread exactly as on windows. gui_host_hwnd hands back the NSWindow. gui_host_run idles on
gui::wait_input and os::sleep_ms in place of the win32 wait and Sleep, so it is the same loop on both
probes/abi-smoke-mac.c is the proof, plain c against the dylib, make abi-smoke, run by hand bc it
opens a window
events go one way, P1.24
nothing in here ever calls a script. an event is queued n the script is woken with a
PostMessage, which is the only call that is safe from any thread, n it comes n drains on its own
thread. so there is no function pointer to marshal n no way to end up running script code on the
wrong thread, which is the whole of what the plan asked for
two things stop it drowning a caller, one wake per drain n not one per event, n sized n
dpi overwrite the one already queued rather than piling up, bc a drag fires hundreds of those n
only the newest says anything. finn called the coalescing 2026-09-05
a click is in the list, gui_event_click, fired off clickable_t::set_on_click n looked up
against the window at the moment it fires rather than captured up front, the same bargain the
overlay dismiss makes
P1.43, the pick n the value
create is the whole of the concrete surface n there are no getters, so before P1.43 the queue was the only channel a script had n it carried the fact of a press n nothing else. a list said something was clicked n handed over a row that is not a handle, a slider said it was pressed n never said where it landed. two kinds close that, n both are appended so nothing a script already hardcoded moved
gui_event_select, the pick,ctrlthe CONTAINER ni0its index. wired onlist,nav_list,dropdown,segmentedntable, inabi::changing, oneif constexprbranch each. a segmented strip fires only on a real CHANGE where a list n a table fire on every pick, bc that is what the c++ side does n the boundary does not second guess itgui_event_value, the number,f0where it landed, onslidernstepper
a row is not a handle n that is the load bearing fact under both. only a control born in
abi::made is registered, n a list taker builds its rows inside its own ctor, so gui_control_at on
a list refuses with gui_err_unmade (it handed back a NULL on a gui_ok until abi 4, see above), n a
click fired on a row comes out of gui_event_next with a null ctrl too, the registry check doing
exactly its job. so the click on a row carries i0 as well, wired by a subtree walk in made bc
is_base_of_v never sees a row, n abi::index_of reads it back off the three types that know their slot
that click is not a duplicate of the select, it is what still fires when the pick did NOT move, e.g. a second press on the segment already active
a rebuild throws those rows away n builds new ones with no hook on them. no export calls
list_t::rebuild today, which is the only reason wiring at create is enough, n the first one that
does calls clicking_below again straight after
a window on its own thread, P1.24
gui_host_spawn is the third pump entry, the window is built on a NEW thread n the caller carries
on. gui::spawn_ui_thread grew a ui_hooks_t for it rather than the abi starting a thread of its
own, so pump.h still spawns one in exactly one place, which is a criterion over there n not a note
what makes it safe is the scene lock, one mutex over the tree, the loose list n every windows queue. the far thread holds it for its WHOLE pass, the message drain included, bc dispatching a resize reaches into the tree n a lock round only the frame would miss the half that races. it sits above the registry lock in one fixed order, scene then registry, which is what stops a freed control deadlocking on its own leaving hook
the split is win32 affinity n nothing else, n as of 2026-09-10 the host block is actually split on it rather than refused wholesale. a spawned windows desc n root still go in AT SPAWN, bc a window cannot be shown, moved or resized from anywhere but its own thread. everything else is reachable from any thread
| from any thread | thread bound |
|---|---|
| the tree, the tweens, the queue | show close move resize |
closed frames root running | update paint pump run |
hwnd size logical dpi scale maximised | set_opacity set_partial_present |
hit_test hovered captured focused set_focus | set_root |
invalidate invalidate_box set_frame |
the left column all takes with_host_live, which is with_host with the thread check off n a null
host check on, see abi.h. it is safe bc the far thread holds the scene lock for its whole pass, so
the win32 side writes m_size n m_dpi under the same lock we read them under. an invalidate from
over here lands on the next pass rather than waking anything, which is fine, the loop comes back round
every pass n never sits in a GetMessage
probes/abi-smoke.c walks the lot on 312 checks n is the thing to run when any of this moves. it
carries BOTH halves on purpose, the right column has to keep coming back gui_err_thread or the
left column is passing for the wrong reason n reads identically
what is deliberately not here
- a mutant for any of this,
tools/mutate.pypatches source n rerunswindow.test.exe, n the abi is a different exe it has never had a runner for. so the two directional probe above is what stands in for one, n teaching mutate a second runner is its own job tab_barntoast_host, they construct fine off a scalar but do nothing until a tab is added or a toast pushed, which is a small api of its own like the item builders were, see below- synthesised input (a scripted mouse move through the router), nothing asked for it yet
scroll_view_t, it needs a subclass to draw its content, which is a callback
adding a control export
one line inside a guarded body, *_out = abi::to_handle(abi::made<gui::button_t>(...));, n made
registers it, parks it loose n hooks its leaving. every generic call in abi_scene.cpp then works
on it with nothing else to write, which is why abi_controls.cpp is create n nothing else
twenty one are in, label, button, badge, checkbox, toggle, panel, progress, slider, stepper, key
value, clickable, icon button, icon view, list, dropdown, nav list, segmented, table, n the text
family, input, area n code editor. the arguments are the ones the c++ constructor takes n nothing
more, bc a create that quietly differs from the c++ one is a second api to keep in step. a callback
argument is the one exception, clickables set_on_click is wired to gui_event_click rather than
exposed, n P1.43 wired every selection n value callback the same way, so a create still takes an
empty one n the queue is where it comes out
an icon is its own handle kind, gui_icon_t, BORROWED by every icon_button n icon_view pointed
at it same as a theme, create hands back an empty one n gui_icon_parse fills it from svg text
the list takers build off a small api of their own, gui_items_t for list, dropdown n
nav_list (a row of text n an optional icon, or a section header that can never be picked), n
gui_cols_t plus gui_rows_t for table. segmented takes a gui_items_t too n just reads the
text off it, the icon n the header both being nothing it understands. every builder is only ever
READ by a create, same bargain a gui_desc_t makes, so it can build a second control off the same
bag or be dropped straight after
only tab_bar n toast_host are still gaps, n for the reason above, not this one
the pump has an opinion
the lib never repaints off a message, so all three entries drain, tick the tweens, then update(),
in that order, gui_host_pump off a timer, gui_host_run blocking, n the spawned loop over on its
own thread. a script that never calls one of them has a window that never moves, n that is the whole
reason they exist rather than the script calling pump_once