com.blockether.spel.helpers — com.blockether/spel 0.5.27

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).}

color-palette! clj

(color-palette! page)

Builds a page color inventory from computed text/background/border colors.

Uses one bulk JavaScript evaluation to aggregate unique colors, usage frequency, near-duplicate color pairs, and coarse hue grouping for palette consistency checks.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :total-colors - Long. Number of unique colors found. :colors - Vector of color maps: {:hex - String (#rrggbb). :rgb - String (rgb). :usage-count - Long. :properties - Vector of property keywords (:color, :background-color, :border-color). :elements-sample - Vector of up to 5 element selectors.} :near-duplicates - Vector of close color pairs: {:color1 :color2 :delta} :hue-groups - Map of grouped hex colors: {:reds [] :blues [] :greens [] :neutrals [] :other []}.

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.

font-audit! clj

(font-audit! page)

Audits typography usage consistency across visible text elements.

Runs one bulk JavaScript pass that aggregates primary font family usage, font-size/weight distributions, and emits basic consistency issues.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :fonts - Vector of {:family :usage-count :elements-sample}. :sizes - Vector of {:px :rem :usage-count}. :weights - Vector of {:weight :usage-count}. :issues - Vector of {:type :description}. :stats - {:font-count :size-count :weight-count}.

heading-structure! clj

(heading-structure! page)

Validates heading hierarchy and order from h1..h6 in DOM sequence.

Uses one lightweight JavaScript evaluation over heading tags only, returning heading entries in document order with structural issues (missing/multiple h1, skipped levels, abrupt order drops).

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :headings - Vector of {:level :text :tag :index}. :issues - Vector of {:type :description :at-index}. :valid? - Boolean. :stats - {:h1 :h2 :h3 :h4 :h5 :h6}.

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}.

layout-check! clj

(layout-check! page)

Checks page layout for common rendering integrity issues in one bulk pass.

Detects horizontal overflow, offscreen elements, flex child overflow, and overlapping element rectangles (excluding fixed/sticky/hidden/transparent nodes from overlap analysis). Overlap candidate checks are capped for performance.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :viewport - {:width :height}. :issues - Vector of issue maps: {:type - Keyword (:horizontal-overflow, :offscreen, :overlap, :flex-overflow). :description - String. :severity - Keyword (:high, :medium, :low). :elements - Vector of {:tag :selector :bbox}.} :total-issues - Long. :clean? - Boolean.

link-health! clj

(link-health! page)

Checks link health using in-page bulk collection plus parallel HEAD requests.

Uses a single page/evaluate call to collect anchor tags, validate hash anchors, skip non-HTTP protocols, and classify fetched URL statuses (2xx/3xx/4xx/5xx, timeout, network error). Results are capped to 100 links for performance.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :total-links - Long. Number of link entries checked (after cap). :ok - Long. Links classified as ok. :broken - Long. Links classified as broken. :redirects - Long. Links classified as redirects. :timeouts - Long. Links classified as timeout. :warning - String or nil. Truncation note when link cap is hit. :links - Vector of link result maps: {:href :status :status-text :type :anchor? :element-text}.

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.

text-contrast! clj

(text-contrast! page)

Audits text contrast across visible text elements using WCAG 2.1 contrast rules.

Uses one bulk JavaScript evaluation to collect up to 500 text-bearing elements, resolve foreground/background colors (including transparent/background-inheritance handling), and compute contrast ratio + AA/AAA pass status.

Params: page - Playwright Page instance.

Returns: Map with: :url - String. Current page URL. :total-elements - Long. Number of analyzed text elements. :passing - Long. Elements passing WCAG AA. :failing - Long. Elements failing WCAG AA. :elements - Vector of element maps sorted with failures first: {:selector - String. :text - String (trimmed preview). :color - String (rgb). :bg-color - String (rgb). :contrast-ratio - Double. :font-size - Double (px). :wcag-aa - Boolean. :wcag-aaa - Boolean. :large-text? - Boolean.}