feat(sdk): a Data App's structure, read from its markup, in the inspect panel

[nkhdo]

A Data App can mark its parts in its own HTML. The inspect panel in anfra serve then shows them as a tree, like a browser's element inspector: hover a node to see it on the page, click to scroll to it, pick one from the page, and copy a handle for an agent.

Markup

Five attributes. data-anfra-container="id" and data-anfra-block="id" name the parts, with an optional data-anfra-label. data-anfra-query and data-anfra-control go on the elements an entity draws into, as name or app/name. Ids are unique per kind. A block holds no container or block, and a control lives in a block the way a query does.

The markup is optional. A wrong name, a duplicate id or a block inside a block shows up as a sentence on that node in the tree. Nothing throws.

SDK

While a host inspects, the app runtime reads the attributes into a tree and posts it with the snapshot, along with how many places draw each entity and in which blocks. A mutation observer keeps the tree current; it watches elements coming and going and the five attributes, and nothing else. A frame nobody inspects does no work.

Declaring a query, control or mapping now notifies subscribers, so an app that adds charts while it runs shows them in the panel right away instead of after their first run.

The host sends three new messages, anfra:highlight, anfra:locate and anfra:pick-watch, and the frame sends anfra:picked back. MountedDataApp gains highlight, locate, setPicking and an onPick callback.

The frame draws one overlay over the marked element: a tinted box and a label with the kind, the id or name in bold, the author's label, a note such as "1 of 3" when the entity is drawn in several places, and the size. query.locate() and control.locate() find their marked elements and flash the same overlay. Hidden elements get the overlay whenever they have a box, which is what devtools does.

appserve

The inspect panel has two tabs. Structure has a toolbar with Pick and Copy handle, the tree under it, and a detail pane for the selected node with its handle and a copy button on that row. Pick ends on a click on the page, on Escape, or on a click in the tree, and clears the overlay. Copy handle gives something like [Revenue over time](data-anfra-block="trend"). Data has the cards from before; each one says in how many places and which blocks its entity is drawn, and has a Locate button.

Checks

make check and make test pass. New SDK tests cover parsing, the tree and its problems, usage, the overlay, pick mode and declaring. I tried it by hand in appserve on three Data Apps: hover, locate, pick, copy, the Data tab, elements added after load, and an app's own locate button.

Left for later: reading the structure from the file without running it, exposing it to author code, and doing anything special for hidden content.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces element bindings to the Anfra SDK, allowing queries and controls to be bound to DOM elements via CSS selectors. It also implements a 'locate' feature that enables the host to request the frame to scroll to and highlight these bound elements. The UI has been updated with 'Locate' buttons in the inspect panel, and comprehensive tests have been added. The review feedback highlights two important improvements in 'elements.ts': ensuring the 'unbind' method trims input selectors to match 'bind' and avoid silent failures, and replacing the unsafe '(element as HTMLElement).offsetWidth' cast with 'element.getBoundingClientRect()' to safely trigger reflows on both HTML and SVG elements.