How it works

The pipeline

1. Input

You provide HTML via the web UI or REST API — as a snippet, an uploaded .html file, or a URL to crawl.

2. API route

A Next.js App Router API route receives your input, resolves or creates a session ID, and calls @openkova/core.

3. Puppeteer render

A long-lived headless Chromium instance (1280×800 viewport) loads the HTML — either via page.setContent() for snippets/files or page.goto() for URLs. It waits for networkidle0 before capturing.

4. Storage

The PNG buffer is saved by LocalStorageAdapter under OPENKOVA_STORAGE_PATH/<sessionId>/<imageId>.png. The StorageAdapter interface makes it straightforward to swap in S3-compatible storage in Phase 2.

5. Response

The API returns a JSON object with sessionId, imageId, and a url pointing to /api/image/… where the PNG is served with proper caching headers.

URL crawling

When you submit a URL, Openkova fetches the page, extracts all same-origin <a href> links, deduplicates them, and screenshots each one (up to 10 pages). The crawl depth controls whether linked pages are also followed.