Page annotation with ref labels, bounding boxes, and dimensions.
Injects CSS overlays directly into the page DOM. Overlays persist until
explicitly removed with remove-overlays!. No AWT dependency — works in
GraalVM native-image without any java.awt configuration.
Usage: (def snap (snapshot/capture-snapshot page)) (inject-overlays! page (:refs snap)) ;; overlays now visible on page ;; ... inspect, screenshot, etc. ... (remove-overlays! page) ;; clean up
Page annotation with ref labels, bounding boxes, and dimensions. Injects CSS overlays directly into the page DOM. Overlays persist until explicitly removed with `remove-overlays!`. No AWT dependency — works in GraalVM native-image without any java.awt configuration. Usage: (def snap (snapshot/capture-snapshot page)) (inject-overlays! page (:refs snap)) ;; overlays now visible on page ;; ... inspect, screenshot, etc. ... (remove-overlays! page) ;; clean up
(annotated-screenshot page refs)(annotated-screenshot page refs opts)Takes a screenshot with annotation overlays (convenience function).
Injects CSS overlays into the page, takes a screenshot, then removes them. Only annotates elements visible in the current viewport. No AWT dependency — everything is done in the browser.
Params:
page - Playwright Page instance.
refs - Map from capture-snapshot.
opts - Map, optional.
:scope - String. CSS selector or snapshot ref (@e1, e1) to restrict
annotations to a subtree.
:show-dimensions - Boolean (default true). Show width x height in labels.
:show-badges - Boolean (default true). Show compact labels.
:show-boxes - Boolean (default true). Show bounding box outlines.
:full-page - Boolean (default false). Capture full scrollable page.
Returns: byte[] of the annotated PNG.
Takes a screenshot with annotation overlays (convenience function).
Injects CSS overlays into the page, takes a screenshot, then removes them.
Only annotates elements visible in the current viewport.
No AWT dependency — everything is done in the browser.
Params:
`page` - Playwright Page instance.
`refs` - Map from capture-snapshot.
`opts` - Map, optional.
:scope - String. CSS selector or snapshot ref (@e1, e1) to restrict
annotations to a subtree.
:show-dimensions - Boolean (default true). Show width x height in labels.
:show-badges - Boolean (default true). Show compact labels.
:show-boxes - Boolean (default true). Show bounding box outlines.
:full-page - Boolean (default false). Capture full scrollable page.
Returns:
byte[] of the annotated PNG.(check-visible-refs page refs)Runs JavaScript in the page to determine which refs are truly visible.
Two-phase check for each ref:
Returns a set of ref IDs that are actually visible.
Runs JavaScript in the page to determine which refs are truly visible. Two-phase check for each ref: 1. Multi-point elementFromPoint (center + 4 inset corners) — pierces invisible overlays (opacity:0, visibility:hidden, pointer-events:none). Walks up from hit element checking for matching data-pw-ref. 2. Fallback: direct style check — queries the element by data-pw-ref and verifies computed display/visibility/opacity. Catches elements under transparent containers (e.g., a logo under a transparent navbar). Returns a set of ref IDs that are actually visible.
(filter-annotatable refs)Filters refs to only those worth rendering as overlays.
Two-step process:
Returns a subset of refs suitable for build-inject-js.
Filters refs to only those worth rendering as overlays. Two-step process: 1. Remove structural roles (paragraph, list, span, etc.) 2. Remove containers whose bbox fully wraps a smaller ref Returns a subset of refs suitable for `build-inject-js`.
(inject-overlays! page refs)(inject-overlays! page refs opts)Injects annotation overlays into the page DOM for visible elements only.
Four-phase filtering pipeline: 0. Scope filter: restrict to refs within a CSS selector's DOM subtree
Params:
page - Playwright Page instance.
refs - Map from capture-snapshot. {"e1" {:role :name :bbox {:x :y :width :height}} ...}
opts - Map, optional.
:scope - String. CSS selector or snapshot ref (@e1, e1) to restrict
annotations to a subtree. Only elements that are descendants
of the matched element will be annotated. Requires prior
snapshot (elements tagged with data-pw-ref).
:show-dimensions - Boolean (default true). Show width x height in labels.
:show-badges - Boolean (default true). Show compact labels.
:show-boxes - Boolean (default true). Show bounding box outlines.
Returns: count of annotated elements (long).
Injects annotation overlays into the page DOM for visible elements only.
Four-phase filtering pipeline:
0. Scope filter: restrict to refs within a CSS selector's DOM subtree
1. Annotation filter: skip structural roles + remove containers
2. Clojure-side: bbox-in-viewport pre-filter (fast, no JS roundtrip)
3. JS-side: elementFromPoint check at each center (detects occlusion,
hidden CSS, aria-hidden, and verifies semantic role match)
Params:
`page` - Playwright Page instance.
`refs` - Map from capture-snapshot. {"e1" {:role :name :bbox {:x :y :width :height}} ...}
`opts` - Map, optional.
:scope - String. CSS selector or snapshot ref (@e1, e1) to restrict
annotations to a subtree. Only elements that are descendants
of the matched element will be annotated. Requires prior
snapshot (elements tagged with data-pw-ref).
:show-dimensions - Boolean (default true). Show width x height in labels.
:show-badges - Boolean (default true). Show compact labels.
:show-boxes - Boolean (default true). Show bounding box outlines.
Returns: count of annotated elements (long).(remove-containers refs)Removes refs whose bbox fully contains another ref's bbox.
When a parent element fully wraps a child (e.g., paragraph around a link), the parent is suppressed to avoid overlapping boxes and labels. Ties on identical-size bboxes are broken by ref ID (lower ID kept).
Removes refs whose bbox fully contains another ref's bbox. When a parent element fully wraps a child (e.g., paragraph around a link), the parent is suppressed to avoid overlapping boxes and labels. Ties on identical-size bboxes are broken by ref ID (lower ID kept).
(remove-overlays! page)Removes all annotation overlays from the page DOM.
Returns: nil.
Removes all annotation overlays from the page DOM. Returns: nil.
(save-annotated-screenshot! page refs path)(save-annotated-screenshot! page refs path opts)Takes an annotated screenshot and saves it to a file.
Params:
page - Playwright Page instance.
refs - Map from capture-snapshot.
path - String. File path for the output PNG.
opts - Map, optional. Same as annotated-screenshot (supports :scope).
Returns: nil.
Takes an annotated screenshot and saves it to a file. Params: `page` - Playwright Page instance. `refs` - Map from capture-snapshot. `path` - String. File path for the output PNG. `opts` - Map, optional. Same as annotated-screenshot (supports :scope). Returns: nil.
(visible-refs viewport refs)Filters refs to only those whose bbox is at least partially visible within the given viewport dimensions.
viewport — {:width N :height N}
refs — snapshot refs map
Filters refs to only those whose bbox is at least partially visible
within the given viewport dimensions.
`viewport` — {:width N :height N}
`refs` — snapshot refs mapcljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |