window

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

filewhat it is
window_abi_tools.hthe public header for the tool exports, the twin of ../window_abi.h
abi_tools.cppthe impl, the only source the tools project adds over the release one

what is in it

exportwhat it answers
gui_tools_versionwhich tools surface this dll speaks, the handshake
gui_tools_treethe control tree under a control, one json document
gui_tools_framewhat the windows frames are doing, one json document
gui_tools_snapthe window redrawn into a png
gui_tools_overlaythe same png with the dirty box and every controls bounds over it
gui_tools_eventsthe 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_arg n writes NOTHING, never a partial document, bc half a json object parses as an error somewhere else n reads as the tool being broken
  • _len is 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 carries null there, the same fact gui_err_unmade reports on gui_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

bandtokens
freeunder 50, a number or a path
low50 to 300
average300 to 1500
high1500 to 6000
xhigh6000 up
toolcostwhat it scales with
gui_tools_versionfreenothing, one int
gui_tools_framefreenothing, 165 bytes measured and the shape is fixed
gui_tools_snapfree to callnothing, it hands back a path
gui_tools_overlayfree to callnothing, it hands back a path
gui_tools_eventslow to averageentries, ~76 bytes each, capped at 64 so ~2k tokens worst case
gui_tools_treelow to xhighnodes, ~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_version resolves on the tools dll and fails on the shipping one, which is the exact question an ahk script asks through Kit.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.Tools and never assembles a DllCall by 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

On this page