@molecule/api-screenshots

Provider-agnostic screenshot capture interface for molecule.dev.

Defines the ScreenshotProvider interface for capturing images of a URL or an HTML string. Bond packages (Puppeteer in-process, molecule.dev hosted) implement this interface. Application code uses the capture convenience function, which delegates to the bonded provider.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, capture } from '@molecule/api-screenshots'
import { provider as puppeteer } from '@molecule/api-screenshots-puppeteer'

setProvider(puppeteer)
const png = await capture({ url: 'https://example.com' }, { width: 1280, height: 800 })
const og = await capture({ html: '<h1>Hello</h1>' }, { width: 1200, height: 630 })

Type

core

Installation

npm install @molecule/api-screenshots @molecule/api-bond @molecule/api-i18n

API

Interfaces

CaptureSource

What to capture — a URL to navigate to, or an HTML string to render. Exactly one of the two must be given.

interface CaptureSource {
  /**
   * The page to visit, `http:` or `https:`. A browser-engine provider fetches
   * what this page names with YOUR server's network access (SSRF) — never
   * point it at an address you would not open yourself, and prefer
   * HTML-escaping any user-supplied URL before building the capture call.
   */
  url?: string

  /** The HTML to render — a full document or a fragment. */
  html?: string
}

ScreenshotOptions

Options for one capture.

interface ScreenshotOptions {
  /** Viewport width in CSS pixels. Bounded by each provider (16–3840). Defaults to `1280`. */
  width?: number

  /** Viewport height in CSS pixels. Bounded by each provider (16–3840). Defaults to `800`. */
  height?: number

  /**
   * Capture the whole scrollable page instead of the viewport. Providers cap
   * how tall a capture may get — a hostile page's `scrollHeight` is untrusted
   * input. Defaults to `false`.
   */
  fullPage?: boolean

  /** Output image format. Defaults to `'png'`. */
  format?: ScreenshotFormat

  /** JPEG quality, 1–100. Ignored for `png`. Defaults to `80`. */
  quality?: number

  /** Device scale factor (1–3) — `2` renders the page at twice the pixel density. Defaults to `1`. */
  scale?: number

  /**
   * Milliseconds to wait after the page loads before capturing (0–5000), so
   * scripts and web fonts can finish. Defaults to `0`.
   */
  delayMs?: number
}

ScreenshotProvider

Screenshot capture provider interface.

All screenshot providers must implement this interface. Bond packages (Puppeteer, molecule.dev hosted, …) provide concrete implementations.

interface ScreenshotProvider {
  /**
   * Captures one image of a URL or an HTML string.
   *
   * @param source - What to capture (URL or HTML — exactly one).
   * @param options - Capture options (viewport, format, scale, …).
   * @returns The image bytes (`image/png` or `image/jpeg`).
   */
  capture(source: CaptureSource, options?: ScreenshotOptions): Promise<Buffer>
}

Types

ScreenshotFormat

Output image format.

type ScreenshotFormat = 'png' | 'jpeg'

Functions

setProvider(provider)

Registers a screenshot provider as the active singleton. Called by bond packages during application startup.

function setProvider(provider: ScreenshotProvider): void

• provider — The screenshot provider implementation to bond.

getProvider()

Retrieves the bonded screenshot provider, throwing if none is configured.

function getProvider(): ScreenshotProvider

Returns: The bonded screenshot provider.

hasProvider()

Checks whether a screenshot provider is currently bonded.

function hasProvider(): boolean

Returns: true if a screenshot provider is bonded.

capture(source, options)

Captures an image of a URL or an HTML string through the bonded provider.

function capture(
  source: CaptureSource,
  options?: ScreenshotOptions,
): Promise<Buffer<ArrayBufferLike>>

• source — What to capture (URL or HTML — exactly one).
• options — Capture options (viewport, format, scale, …).

Returns: The image bytes.

Available Providers

Provider	Package
Molecule (hosted)	@molecule/api-screenshots-molecule
Puppeteer (screenshots)	@molecule/api-screenshots-puppeteer

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1
• @molecule/api-i18n ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• @molecule/api-i18n

• A browser-engine provider fetches the page — and everything it names — with YOUR server's network access (SSRF). A url: capture navigates to that address and loads its subresources from your machine; an html: capture renders whatever <img src> / CSS url() the markup names. The hosted molecule.dev provider runs every capture through an egress guard that resolves each target itself and dials public addresses only; an in-process bond (Puppeteer) has NO such guard — point it only at URLs you control, and never pass a raw user-supplied URL straight through.

• A hostile page is untrusted input on every axis: its scrollHeight can be enormous (providers cap how tall a fullPage capture may get), its scripts can stall the load event (providers bound the wait and the total capture time), and the returned image is whatever the page drew.

• Results are Buffers: send them with an image/png / image/jpeg response, or store them via the uploads package — never JSON.stringify a Buffer into an API payload.

• Output dimensions depend on the options: the image is width × height × scale pixels for a viewport capture, and as tall as the page (up to the provider's cap) for fullPage.