com.blockether.spel.helpers — com.blockether/spel 0.5.22

High-level agent helpers — opinionated one-shot commands that replace multi-step agent workflows with deterministic, correct-by-default operations.

These functions compose lower-level primitives (screenshot, scroll, snapshot, annotate, evaluate) into the operations AI agents need most often but get wrong when composing manually.

All functions take an explicit Page argument (library layer). SCI wrappers in sci_env.clj provide implicit-page versions.

audit! clj

(audit! page)

Discovers the structural layout of the page — header, nav, main content, footer, sidebar, and other landmark sections.

Uses a three-phase detection strategy:

1. ARIA landmark roles (role='banner', role='main', etc.)
2. Semantic HTML5 tags (<header>, <nav>, <main>, <footer>, <aside>)
3. Common CSS patterns (.header, .nav, .sidebar, etc.)

Elements are deduplicated — if an element matches multiple phases, it appears once (first match wins). Results are sorted top-to-bottom by Y position.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :title - String. Page title. :scroll-height - Long. Total scrollable height. :viewport - {:width :height}. :sections - Vector of section maps: {:type - String (header, nav, main, footer, aside, search, form, section, article). :source - String (aria-role, semantic-tag, css-pattern). :tag - String (HTML tag). :id - String or nil. :class - String or nil (first 5 classes). :ref - String or nil (snapshot ref if previously snapshotted). :bbox - {:x :y :width :height}. :text-preview - String (first 100 chars of text content).}

debug! clj

(debug! page)

Collects page-level diagnostic information — the "health check" an agent needs after something breaks or before reporting issues.

Gathers from the Page object directly:

• Performance timing (DNS, TTFB, DOM interactive/complete, load)
• Failed resource loads (0-byte transfers)
• DOM statistics (element count, forms, images, links, scripts)
• Viewport vs content dimensions
• Page metadata (URL, title, readyState)

The daemon handler enriches this with tracked console messages, page errors, and failed network requests from its ring buffers.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :title - String. Page title. :ready-state - String. Document readyState. :timing - Map. Performance timing breakdown (ms). :failed-resources - Vector. Resources that failed to load. :dom - Map. DOM element counts. :dimensions - Map. Viewport and scroll dimensions.

inspect! clj

(inspect! page)

(inspect! page opts)

Takes an interactive snapshot with styles — the 'agent view' of a page.

Combines snapshot flags that agents always need together:

• Interactive elements only (buttons, links, inputs, etc.)
• Computed styles on each element (font-size, color, background, etc.)
• Screen coordinates (pos:X,Y W×H)

This replaces the common pattern of snapshot -i -S with a single call.

Params: page - Playwright Page instance. opts - Map, optional. :compact? - Boolean. Remove bare role-only lines (default: true). :style-detail - String. Style detail level: "minimal", "base", "max" (default: "base"). :scope - String. CSS selector or ref to scope the snapshot. :device - String. Device name (included in tree header).

Returns: Map with same structure as capture-snapshot: :tree - String. YAML-like accessibility tree with styles. :refs - Map of ref-id → element data (includes :styles key). :counter - Long. Total refs. :viewport - {:width :height}.

overview! clj

(overview! page)

(overview! page opts)

Takes an annotated full-page screenshot — a single image showing the entire page with element annotations (ref labels, bounding boxes).

Unlike regular annotated-screenshot which only annotates viewport-visible elements, overview annotates ALL elements on the page by using the :full-page option for both overlay injection and screenshot capture.

Params: page - Playwright Page instance. opts - Map, optional. :path - String. Output file path (if nil, returns bytes only). :show-dimensions - Boolean (default true). :show-badges - Boolean (default true). :show-boxes - Boolean (default true). :scope - String. CSS selector or ref to restrict annotations. :all-frames? - Boolean. Include iframe content via capture-full-snapshot (default: false). When true, the snapshot covers all frames including iframes, not just the main frame.

Returns: If :path is set: {:path "..." :size N :refs-annotated N} If no :path: {:bytes <byte[]> :refs-annotated N}

routes! clj

(routes! page)

(routes! page opts)

Extracts all links from the current page.

Returns every <a href> on the page with resolved URLs, visibility status, and snapshot refs (if a snapshot was taken prior). Links are deduplicated by resolved URL.

Params: page - Playwright Page instance. opts - Map, optional. :internal-only? - Boolean. Only return same-origin links (default: false). :visible-only? - Boolean. Only return visible links (default: false).

Returns: Map with: :url - String. Current page URL. :count - Long. Number of links returned. :links - Vector of link maps: {:text - String. Link text content (trimmed, max 200 chars). :href - String. Fully resolved URL. :raw-href - String. Original href attribute value. :ref - String or nil. Snapshot ref if available. :internal? - Boolean. True if same-origin. :visible? - Boolean. True if the link has a visible bounding box. :bbox - {:x :y :width :height}. :target - String or nil. Target attribute value. :rel - String or nil. Rel attribute value.}

survey! clj

(survey! page)

(survey! page opts)

Scrolls through the entire page taking a screenshot at each viewport position. Returns a vector of maps, one per screenshot: [{:path "...", :y 0, :index 0, :viewport {:width W :height H}} ...]

This is NOT a full-page screenshot — it captures what the agent would 'see' at each scroll position, including any viewport-specific rendering (sticky headers, lazy-loaded content, etc.).

Params: page - Playwright Page instance. opts - Map, optional. :output-dir - String. Directory for screenshots (default: temp dir). :prefix - String. Filename prefix (default: "survey"). :overlap - Long. Pixel overlap between frames (default: 0). :annotate? - Boolean. Inject annotation overlays per frame (default: false). :device - String. Device name to emulate before sweep (e.g. "iPhone 14"). Sets viewport + user-agent, restores original viewport after. :max-frames - Long. Maximum number of frames to capture (default: 50).

Returns: Vector of {:path :y :index :viewport} maps.