com.blockether.spel.helpers — com.blockether/spel 0.9.7

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.

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 :annotated {:count N :entries [...]}} If no :path: {:bytes <byte[]> :annotated {:count N :entries [...]}}

The :annotated value is a deterministic, top→down/left→right-sorted list of actually-drawn elements (after role + container + visibility filtering). Each entry is {:ref :role :name :bbox}. This is the LLM-friendly mapping between labels on the image and snapshot refs that can be used for subsequent interactions (e.g., spel click @e2yrjz).

page-insights! clj

(page-insights! page)

Collects page performance, meta tags, DOM stats, image accessibility, form labels, and resource loading summary in one evaluation.

Params: page - Playwright Page instance.

Returns: Map with :timing, :resources, :dom, :images, :meta, :forms, :viewport.

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.