docs: design notes for a live-UI box model - #11
Merged
Merged
Conversation
Analysis only, no implementation. Records what macOS can actually give an LLM about an on-screen layout — element boxes, hierarchy, colours, typography — and where that work belongs. Measured rather than assumed, on an M1 Pro: - AX coverage is much better than earlier notes in this project guessed. Finder returns geometry for 100% of elements, the Electron-based Claude app 99% across 25 levels, Safari 99% including full web content. - AX exposes no styling attributes at all — verified by enumerating every attribute name across four apps — with one exception: AXAttributedStringForRange carries real AXFont family/name/size and alignment, so typography need not be estimated from OCR box heights. - The bottleneck is the AX walk, not pixels: every attribute read is a synchronous IPC round trip. 4001 elements cost 1.57s in Safari but 11.34s in Finder, batched. Colours cost 90ms to decode the capture once and 0.009ms per element after that. Concludes that this belongs here rather than in macos-vision-mcp: the tree walk needs a compiled Swift helper, and this package owns the native-helper pipeline — the same reason ui-helper moved here. Follows the existing inferLayout/buildPageAnalysis split, with composition here and tool shaping in the MCP server. States the limits up front: this is not the CSS box model, padding and border width are inferred rather than measured, occluded elements have untrustworthy colours, and for web pages the DevTools protocol already returns the real thing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Analysis only — no implementation, no code touched.
Answers the question "can we give an agent a JSON box model of a live layout, with colours and borders?" and decides where that work belongs. Everything is measured on an M1 Pro rather than assumed.
What the probes found
AXAttributedStringForRangecarries realAXFontfamily/name/size and alignment, so typography is fact, not an estimate from OCR box heights.Conclusion
Implement here, not in
macos-vision-mcp: the tree walk needs a compiled Swift helper and this package owns the native-helper pipeline — the same reasonui-helpermoved here. Follows the existinginferLayout/buildPageAnalysissplit, with composition here and tool shaping in the MCP server.The doc states the limits up front: this is not the CSS box model, padding and border width are inferred rather than measured, occluded elements have untrustworthy colours, and for web pages the DevTools protocol already returns the real thing.
Merging this unblocks an implementation agent working from
docs/BOX-MODEL.md.🤖 Generated with Claude Code