@a1local/adpages-browser-capture

Adapter layer for turning saved HTML now, and rendered URLs later, into @a1local/adpages-audit-core snapshots.

This package is intentionally small:

• no runtime dependencies
• no Playwright import yet
• no remote crawling in the package itself
• no storage, analytics, or licensing logic

Static HTML Capture

Use captureStaticHtmlSnapshot when a CLI, GitHub Action, local script, or Docker job already has HTML available from disk or stdin.

import { auditLandingPageSnapshot } from "@a1local/adpages-audit-core";
import { captureStaticHtmlSnapshot } from "@a1local/adpages-browser-capture";

const snapshot = captureStaticHtmlSnapshot(html, {
  url: "https://example.com/landing?utm_source=google&utm_medium=cpc&utm_campaign=brand",
  sourceLabel: "saved preview HTML"
});

const audit = auditLandingPageSnapshot(snapshot);

The helper returns the PageAuditSnapshot shape used by audit core. It does not depend on document, window, JSDOM, or browser APIs, so it is safe for Node-only workflows.

Static capture is best for pre-rendered HTML, build artifacts, and existing saved-page audits. It will not see client-rendered content, redirects, cookies, layout, computed accessibility state, network requests, or browser console errors.

CLI Path

The first CLI integration should keep fetching and file I/O outside this package:

1. Read HTML from --html-file, stdin, or a wrapper-owned URL fetch.
2. Call captureStaticHtmlSnapshot(html, { url, sourceLabel }).
3. Pass the snapshot to auditLandingPageSnapshot.
4. Render text, Markdown, JSON, or CI-friendly output in the CLI wrapper.

When URL capture is added, the CLI can accept a rendered-browser adapter that implements BrowserCaptureAdapter without making this package depend on Playwright.

GitHub Action Path

For the existing saved-HTML Action, this package can replace duplicated extraction logic:

1. Checkout the site or receive a preview artifact.
2. Read the saved HTML file.
3. Build a snapshot with captureStaticHtmlSnapshot.
4. Run audit core and publish the report.

For future preview URL audits, the Action should own browser installation, cache settings, secrets, timeouts, and failure policy. The rendered capture implementation can live beside the Action and satisfy the adapter type exported here.

Docker Path

A Docker image can provide the heavier runtime without pushing those dependencies into this package:

1. Install the browser runtime in the image.
2. Run the adapter against one or more URLs.
3. Emit audit-core-compatible snapshots.
4. Run audit core and write reports to mounted output paths.

This keeps local package installs fast while still allowing reproducible URL audits in CI.

Future Remote Capture

Remote capture should be explicit, user-initiated, and monetisation-safe:

• require a supplied URL or preview URL; do not crawl arbitrary sites by default
• keep request timeouts, max pages, and concurrency bounded
• avoid collecting form inputs, cookies, local storage, or authenticated data unless a wrapper explicitly owns that flow
• keep paid-gating, account state, and license checks outside this package
• return deterministic snapshot data that audit core can evaluate locally

The intended future shape is:

import type { BrowserCaptureAdapter } from "@a1local/adpages-browser-capture";

export const captureWithPlaywright: BrowserCaptureAdapter = async (request) => {
  // Wrapper-owned Playwright code goes here later.
  // Return a PageAuditSnapshot compatible with @a1local/adpages-audit-core.
};