com.blockether.spel.snapshot — com.blockether/spel 0.9.9

Accessibility snapshot with content-hash stable refs.

Walks the DOM tree via JavaScript injection and builds a YAML-like accessibility tree with content-hash refs (deterministic across page states). Elements are tagged with data-pw-ref attributes for later interaction.

Usage: (def snap (capture-snapshot page)) (:tree snap) ;; YAML-like string with [@eXXXXX] annotations (:refs snap) ;; {ref-id {:role :name :tag :bbox} ...} (resolve-ref page ref-id) ;; returns Locator for the element

capture-full-snapshot clj

(capture-full-snapshot page)

Captures a snapshot of the page and all its iframes.

Combines main frame and iframe snapshots into a unified tree.

Params: page - Playwright Page instance.

Returns: Map with :tree, :refs, :counter covering all frames.

capture-script clj

(capture-script opts)

Returns the capture-snapshot JS with optional flags injected.

When :scope is provided, the JS walks from the element matching that CSS selector instead of document.body. If the selector matches nothing, the JS returns an empty result.

When :styles is true, each ref'd element includes computed CSS styles in kebab-case CSS property names. The :styles-detail option selects the tier: 'minimal' (16 props), 'base' (31, default), or 'max' (44).

Scope can be a CSS selector or a snapshot ref (@e2yrjz).

Backend-neutral: the returned script is a self-executing expression that works through Playwright page.evaluate and (wrapped in return (...)) through W3C WebDriver execute-script.

capture-snapshot clj

(capture-snapshot page)

(capture-snapshot page opts)

Captures an accessibility snapshot of the page with numbered refs.

Injects JavaScript to walk the DOM, compute ARIA roles and names, assign data-pw-ref attributes, and collect bounding boxes.

Params: page - Playwright Page instance. opts - Map, optional. :scope - String. CSS selector or snapshot ref (@e2yrjz, e2yrjz) to scope the snapshot to a subtree. When provided, only elements within the matched element are included in the tree and refs. If the selector matches nothing, returns an empty snapshot.

Returns: Map with: :tree - String. YAML-like accessibility tree with [@eXXXXX] annotations. :raw-tree - The raw nested tree structure from the accessibility snapshot JS. :refs - Map. {'e2yrjz' {:role 'button' :name 'Submit' :bbox {:x :y :width :height}} ...} :counter - Long. Total number of refs assigned.

capture-snapshot-for-frame clj

(capture-snapshot-for-frame _frame frame-ordinal)

Captures an accessibility snapshot for a specific frame.

Refs are prefixed with the frame ordinal: f1_e1, f2_e3, etc.

Params: frame - Playwright Frame instance. frame-ordinal - Long. Frame index (1-based).

Returns: Same format as capture-snapshot, but with prefixed refs.

capture-webdriver clj

(capture-webdriver driver)

(capture-webdriver driver opts)

Captures an accessibility snapshot through a W3C WebDriver session.

Reuses the same capture script as the Playwright adapter — the WebDriver evaluate wrapper adds the return (...) required by execute-script semantics. Viewport is read from the page via JavaScript because WebDriver has no direct viewport API for web content.

Frames are NOT walked — this is a main-frame-only snapshot (iOS MVP).

Params: driver - com.blockether.spel.webdriver WebDriverSession. opts - Same options as capture-snapshot (:scope, :styles, ...).

Returns the same map shape as capture-snapshot.

clear-refs! clj

(clear-refs! page)

Removes all data-pw-ref attributes from the page.

Params: page - Playwright Page instance.

diff-snapshots clj

(diff-snapshots baseline current)

Compares two accessibility snapshot strings line-by-line.

Returns a map with diff statistics and individual line changes.

Params: baseline - String. The baseline snapshot text. current - String. The current snapshot text.

Returns: {:added N :removed N :changed N :unchanged N :diff [" line" "- old" "+ new" ...]}.

flatten-tree clj

(flatten-tree tree)

Flattens a YAML-like tree string by stripping all leading whitespace. Each node appears at depth 0, removing the nested hierarchy.

Useful for AI agents that need a simple list of elements without nesting structure.

Params: tree - String. YAML-like accessibility tree from capture-snapshot.

Returns: String with all lines at depth 0, or nil if tree is nil.

parse-capture-result clj

(parse-capture-result result)

(parse-capture-result result opts)

Parses the raw JS capture result into the public snapshot map.

Backend-neutral: result is the map returned by the capture script — a java.util.Map from Playwright evaluate or a Clojure map from WebDriver execute-script (both string-keyed).

Params: result - Map with "tree", "refs", "counter" keys. opts - Map, optional: :viewport - Map {:width :height} for the tree header. :device - String device label for the tree header.

Returns: Map with :tree, :raw-tree, :refs, :counter, :viewport, :device.

ref-bounding-box clj

(ref-bounding-box refs ref-id)

Returns the bounding box for a ref from the last snapshot.

Params: refs - Map of refs from capture-snapshot. ref-id - String. Content-hash ref like "e2yrjz".

Returns: Map {:x :y :width :height} or nil.

ref-css-selector clj

(ref-css-selector ref-id)

Returns the CSS selector for a snapshot ref id.

Accepts bare (e2yrjz) or prefixed (@e2yrjz) refs. Backend-neutral — used by both Playwright and WebDriver ref resolution.

resolve-ref clj

(resolve-ref page ref-id)

Resolves a ref ID to a Playwright Locator.

The element must have been tagged with data-pw-ref during capture-snapshot.

Params: page - Playwright Page instance. ref-id - String. Bare ref ID without @ prefix (e.g. e2yrjz).

Returns: Locator instance for the element.