the tools dll
the live tree, the frame state, a snapshot and the last events
mirrored from
window/cpp/abi/tools/README.md, which is the only copy of this text. edits made here are overwritten the next time the site builds
everything in this folder is compiled into window.abi.tools.dll and into nothing else. the shipping
dll, window.abi.dll, has never been handed a single file from in here
| file | what it is |
|---|---|
window_abi_tools.h | the public header for the tool exports, the twin of ../window_abi.h |
abi_tools.cpp | the impl, the only source the tools project adds over the release one |
what is in it
| export | what it answers |
|---|---|
gui_tools_version | which tools surface this dll speaks, the handshake |
gui_tools_tree | the control tree under a control, one json document |
gui_tools_frame | what the windows frames are doing, one json document |
gui_tools_snap | the window redrawn into a png |
gui_tools_overlay | the same png with the dirty box and every controls bounds over it |
gui_tools_events | the last few events on the window, one json document |
all five tools are in, P1.41 is closed. the three shapes are a document tool (_buf, _cap,
_len, see the text contract below), a png tool (a path in, a file out) and the version handshake
the text contract, every document tool uses it
ask for the size, then ask for the text. one call with a null _buf n a _cap of 0 fills _len
with the byte count, then a second call with a buffer of at least _len + 1 fills it. two calls is
deliberate, an ahk caller has to size a Buffer before it can hand one over n guessing is how a
document gets truncated
- a buffer too small is
gui_err_argn writes NOTHING, never a partial document, bc half a json object parses as an error somewhere else n reads as the tool being broken _lenis filled on the refusal too, so a caller that guessed wrong learns the real size from the same call rather than starting over- a handle inside a document is a hex STRING,
"0x7ff6a12c40", bc a 64 bit pointer does not survive a json parser backed by a double n a silently rounded handle is worse than no handle. a control this dll never made carriesnullthere, the same factgui_err_unmadereports ongui_control_at
Kit.Tools.Doc on the ahk side does both calls, so a wrapper method is one line
the frame
{"frames":,"paced":,"dirty":{"any":,"full":,"partial":,"box":[]},"last":{...}}, and every box is
SURFACE px bc that is the space the dirty model works in, i.e. the logical box times the scale on a
hidpi monitor and the same number on a normal one
dirty is what the next frame owes, last is what the last one that really landed did, so it
reads {"i":,"box":[],"repaint":"full"|"partial","present":"full"|"partial","scale":,"us":} and is
null until a frame has happened at all
the model used to decide all of this and then throw it away. frame_stat_t in host/dirty.h is
new for this tool, stamped in host_t::update() once a frame has really landed, so a refused frame
leaves the last real one alone. what is kept is the plan rather than what draw_frame resolved
against the real surface, bc the bug worth catching is nearly always the model asking for the wrong
thing, and the two only differ when it does
us is the whole draw and present measured with QPC, not just the paint callback. GetTickCount64 is
what the pump uses and it cannot see a frame at all, most of them come in under its ~15ms tick
the two pngs
both REDRAW the tree into plain memory and write that out, they do not lift pixels off the live surface. so no hwnd is touched, no dc is opened, the presenter is never asked for anything, and both work for a spawned window from the script thread like every other reader here. it is P1.31s harness pointed at a live window, which is exactly what the plan asked for
the cost of that is what it says on the tin, it is the tree drawn again and not a photograph of the glass. anything the compositor did after the present is not in the png, and that is usually the point, the question is nearly always what the lib drew rather than what the desktop ended up showing
- the parent folder has to already exist, same bargain as
dump_scene, a lib quietly making directories on somebody elses disk is worse than one that says it could not write - a failed write is
gui_err_internal, and a window with no root is a cleared png rather than a refusal - the overlay strokes control bounds in green and the dirty box in magenta over the top, and the dirty box only when there is one, so an empty overlay means the next frame owes nothing rather than meaning the tool did not run
the event tail
{"seen":,"events":[{"seq":,"kind":,"n":,"i0":,"i1":,"f0":,"ctrl":,"type":}]}, oldest first, where
kind is the name and n the number
THE TAIL IS NOT THE QUEUE AND DOES NOT TOUCH IT. a script drains the queue, the tail keeps its own fixed ring of 64 behind that, so reading it never costs a script an event it was going to be handed and asking twice answers the same thing
it records events NOBODY SUBSCRIBED TO, and that is the whole design. the mechanism is one function
pointer, abi::event_spy, declared in abi.h and called at the top of push_event above the
wants mask. the only thing that ever installs one is a static in abi_tools.cpp, which the shipping
dll never compiles, so release carries one null compare per event and nothing else. a click that went
to the wrong control is nearly always a click nothing was watching, so a tail behind the mask would be
blind to precisely its own case
the ring is shared across every window, so a busy window can push a quiet ones entries out. seq is
what says so, a gap in it is real and means the ring wrapped. ctrl and type are captured at the
moment of the event rather than looked up later, bc by the time anybody reads the tail the control it
names has often been destroyed
the tree
every node is {"h":,"type":,"box":[x,y,w,h],"vis":,"en":,"kids":[]}, type being the c++ class
name off rtti n box the LOGICAL px box the layout put it in. it is rtti n not a kind stamped at
create bc there is no such stamp, the abi has always asked a control what it is with a dynamic_cast
it walks the REAL children n not the registry, so a list takers rows are in the document even
though none of them has a handle. they read "h":null, which is the same fact gui_control_at
reports as a status, written in a form a parser can use
what each one costs you in context
for the api page, which is not written yet. the caller is nearly always an agent, so how much of
its window an answer eats is part of the surface, the same way a return type is. the bands here are
estimated off real byte counts taken from tools-smoke, at roughly 3 bytes to the token, which is
about right for json this punctuation dense. they are not measured token counts
| band | tokens |
|---|---|
| free | under 50, a number or a path |
| low | 50 to 300 |
| average | 300 to 1500 |
| high | 1500 to 6000 |
| xhigh | 6000 up |
| tool | cost | what it scales with |
|---|---|---|
gui_tools_version | free | nothing, one int |
gui_tools_frame | free | nothing, 165 bytes measured and the shape is fixed |
gui_tools_snap | free to call | nothing, it hands back a path |
gui_tools_overlay | free to call | nothing, it hands back a path |
gui_tools_events | low to average | entries, ~76 bytes each, capped at 64 so ~2k tokens worst case |
gui_tools_tree | low to xhigh | nodes, ~78 bytes each, and nothing caps it |
the two that need reading properly
gui_tools_tree is the only unbounded one. measured at 471 bytes over 6 nodes, so about 26 tokens
a node. a small dialog is low, a hundred node app tree is average to high, and a table with
five hundred rows in it is xhigh and will hurt, bc every row is a real node with a box on it
so pass a control and not the root when you can. the tool takes any control, the subtree under it is the document, and narrowing the question is the whole cost control here
the pngs are free to CALL and expensive to LOOK AT. the call returns a path and nothing else, so
the export itself is free whatever the window size. the cost lands when an agent actually reads the
image, which is roughly width * height / 750 tokens, i.e. ~85 for a 320x200 probe window and
~1400 for a real 1280x800 one, so high in practice. reach for gui_tools_tree first, an eye
is what the overlay is for and a parser answers most questions cheaper
the size question is free, use it
every document tool answers _cap 0 with a null _buf by filling _len and writing nothing, so
you can ask what an answer would cost before you commit to it. that is there for the buffer
contract, but it doubles as the one lever an agent has over its own window, ask the size, and narrow
the question when the number is bigger than the answer is worth
the compile out is FILE SELECTION, not a preprocessor switch
there is no GUI_ABI_TOOLS define, no #ifdef in the lib and none to add. the two projects import
the same ../abi.shared.props, which carries every source, every reference and the golden header check,
and window.abi.tools.vcxproj lists exactly one ClCompile the release project does not
that is the whole mechanism, and it is chosen over a define for one reason. a define is a switch somebody can get wrong. it can be set in the wrong config, inherited off a props sheet nobody read, or left on by a copy pasted project, and every one of those ships an inspection surface to a caller who should not have one. a file the release project never lists cannot end up in the release dll at all
the claim is CHECKED and not asserted
test_abi_tools_split in window.test loads both dlls and reads their export tables back
gui_tools_versionresolves on the tools dll and fails on the shipping one, which is the exact question an ahk script asks throughKit.Tools.Available- the shipping dll carries ZERO names starting
gui_tools_, counted off the export table rather than compared against a number, so a whole tools block leaking across cannot pass a check written on one name, and the check needs no editing every time a tool goes in - the two dlls differ by the tools names and by nothing else
it was broken on purpose to prove it bites, tools\abi_tools.cpp added to window.abi.vcxproj, and both
checks failed with 146 exports shipping, 146 tools, gui_tools_version on THE WRONG ONE
tools-smoke.c in probes\ is the other half, linking window.abi.tools.lib, and it has two halves
with a fixed count each
- the default run, 44 checks, headless, no window and no pump, so it still runs over ssh and in a container. that is the whole reason it is a keeper and it is why the windowed checks are not folded into it
tools-smoke --live, 44 checks, a real chromed window. it is the only place the frame stamp, the two pngs and the tail can be driven end to end, bc a handle only means anything to the dll that made it and this probe links the tools one
six mutants have been run across the two sessions and all six died. the first three were the tree,
the subtree walk stopped at the root, every handle forced null, and a short buffer given a truncated
document with an ok on it. the three for the rest were the frame stamp moved above the refused frame
return (caught by test_dirty), the event spy moved below the wants mask (the tail came back
empty), and the overlay made to stroke nothing (both pngs came out at the same byte count)
test_dirty in the suite carries the other eight, over frame_stat_t itself rather than over the tool
that serialises it
the bar a tool has to clear
every one of these exists so an agent can answer a question about a running window without a screenshot and without a person, so a tool that only makes sense to a human eye does not belong in here. the one exception the plan allows is the visual overlay set, and it earns it bc a wrong dirty box is far quicker to see than to read
- it only ever READS, nothing here moves a control, sets a value, forces a frame or frees anything, a tool that changed something would make the dll you inspect a different dll from the one you shipped, which is the one bug an inspection surface must not have
- it answers in a machine readable form, one document out, no alignment and no colour
- it is wrapped like the rest of the surface, an agent calls a named ahk function on
Kit.Toolsand never assembles aDllCallby hand
the version
GUI_TOOLS_VERSION moves independently of GUI_ABI_VERSION, and the freeze rule in ../README.md
does not cover this file. nothing in here is shipped to anybody, so it moves when it needs to
a script does not compare the version to decide whether it is safe, it compares to decide what is there. the safety question is answered by the export resolving at all