scenic-prism-playwright 0.1.0

package/dist/library.js

@@ -0,0 +1,122 @@
+/**
+ * Finding `scenic-prism` on disk, and serving it to the page.
+ *
+ * The trace itself is the library's own `render()`, running in the browser
+ * exactly as it does on a web page — this package never reimplements the render
+ * loop, and never compiles a shader of its own. What it does instead is hand
+ * the browser the very copy of `scenic-prism` the caller has installed, as ES
+ * modules over an intercepted origin, so the image a script saves and the image
+ * that same scene draws in an app come out of the same code.
+ *
+ * `scenic-prism` is not a dependency of this package: `scenic-prism-fluent` is
+ * the peer, and it carries the core at an exact version. So the copy to serve
+ * is the one *the fluent package* resolves, which is what `resolveLibraryRoot`
+ * goes looking for.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The package whose modules are served into the page. */
+const CORE = 'scenic-prism';
+/** The peer that carries it, and through which it is found. */
+const FLUENT = 'scenic-prism-fluent';
+/**
+ * Walk `node_modules` upwards from a directory, the way Node's own resolver
+ * does, and return the root of the first `name` found. Deliberately not
+ * `require.resolve`: this package and the ones it looks for are ESM with an
+ * `exports` map that has no `require` condition, so CommonJS resolution cannot
+ * see them, and `import.meta.resolve` answers with an entry module rather than
+ * with the package root and its manifest — which is what has to be served.
+ */
+export function findPackageRoot(from, name) {
+    let directory = resolve(from);
+    for (;;) {
+        const candidate = join(directory, 'node_modules', name, 'package.json');
+        if (existsSync(candidate))
+            return dirname(candidate);
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+/**
+ * Where the installed `scenic-prism` lives. Looked for beside the fluent
+ * package first — that is the copy the caller's scenes are built with, and the
+ * one whose version the fluent package pins — and only then beside this one,
+ * for an install flat enough to hoist it.
+ */
+export function resolveLibraryRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const starts = [here];
+    try {
+        starts.unshift(dirname(fileURLToPath(import.meta.resolve(FLUENT))));
+    }
+    catch {
+        // `scenic-prism-fluent` is a peer dependency, so a project that has this
+        // package without it is already broken — but a missing peer should be
+        // reported as the missing library below, not as a resolution stack trace.
+    }
+    for (const start of starts) {
+        const root = findPackageRoot(start, CORE);
+        if (root)
+            return root;
+    }
+    throw new Error(`scenic-prism-playwright: could not find '${CORE}' to serve to the browser. ` +
+        `It comes with '${FLUENT}', which is a peer dependency — install that, ` +
+        'or pass `libraryRoot` pointing at the package root to use.');
+}
+/**
+ * The module a browser should import for a package root, as a path relative to
+ * it. Read off the manifest the way a bundler would: the `import` condition of
+ * the main export first, then the legacy fields.
+ */
+export function browserEntry(root) {
+    const manifestPath = join(root, 'package.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`scenic-prism-playwright: no package.json in '${root}'.`);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const main = manifest.exports?.['.'];
+    const conditions = typeof main === 'object' && main !== null ? main : {};
+    const entry = [
+        typeof main === 'string' ? main : undefined,
+        conditions.import,
+        conditions.default,
+        manifest.module,
+        manifest.main,
+    ].find((value) => typeof value === 'string');
+    if (!entry) {
+        throw new Error(`scenic-prism-playwright: '${root}' declares no ES module entry point. ` +
+            'Point `libraryRoot` at an assembled package rather than at a source checkout.');
+    }
+    const relative = entry.replace(/^\.\//, '');
+    if (!existsSync(join(root, relative))) {
+        throw new Error(`scenic-prism-playwright: '${join(root, relative)}' does not exist.`);
+    }
+    return relative;
+}
+/** Content types for the handful of things a package's `dist` holds. */
+export function contentType(path) {
+    if (path.endsWith('.js') || path.endsWith('.mjs'))
+        return 'text/javascript; charset=utf-8';
+    if (path.endsWith('.json') || path.endsWith('.map'))
+        return 'application/json; charset=utf-8';
+    if (path.endsWith('.css'))
+        return 'text/css; charset=utf-8';
+    return 'text/plain; charset=utf-8';
+}
+/**
+ * Resolve a request path against the served root, refusing anything that
+ * climbs out of it. Nothing here is reachable from outside the browser this
+ * package launched, but a scene is data and data comes from somewhere, so the
+ * one place a path could be influenced is still checked.
+ */
+export function resolveServedFile(root, requestPath) {
+    const decoded = decodeURIComponent(requestPath);
+    const full = resolve(root, `.${decoded.startsWith('/') ? decoded : `/${decoded}`}`);
+    const base = resolve(root);
+    if (full !== base && !full.startsWith(base + sep))
+        return null;
+    return full;
+}

package/dist/margin.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The margin: a border of flat colour around a finished image.
+ *
+ * It is deliberately not part of the render. The page is served, the canvas is
+ * sized and the scene is traced exactly as they are without a margin, and the
+ * border is added afterwards, here, to the bytes that came back — so a plate
+ * rendered at `size: 1200` with a margin holds the *same* 1200² of traced image
+ * as one rendered without, sitting in a larger file. Widening the canvas
+ * instead would have widened the field of view with it, which is a different
+ * picture rather than a mounted one.
+ *
+ * That is also why this is the one part of the package that does image work of
+ * its own: everything else hands pixels to the browser or takes them from it,
+ * and a border drawn after the encoding has no browser left to draw it in.
+ * `sharp` is the dependency that pays for it.
+ */
+import type { Vec3 } from 'scenic-prism-fluent';
+import type { ImageFormat } from './image.js';
+/** The border a render can be mounted in. */
+export interface MarginOptions {
+    /**
+     * How many pixels to add on each of the four sides. A whole number, and at
+     * least one — a margin of nothing is a margin nobody meant to ask for.
+     */
+    size: number;
+    /**
+     * What to fill it with, as the `[r, g, b]` triple colours are written as
+     * everywhere else in the library. White by default.
+     *
+     * Unlike a colour in a scene this one is never traced and never tonemapped:
+     * it is the colour of the file, so `[1, 1, 1]` is white, `[0, 0, 0]` is
+     * black, and `[0.5, 0.5, 0.5]` is the middle of the range the file can hold
+     * rather than the middle of a range of light. Components outside 0..1 have
+     * nowhere to go, so they are refused rather than clipped quietly.
+     */
+    colour?: Vec3;
+}
+/** What every generated file gets when no colour is named: paper. */
+export declare const DEFAULT_MARGIN_COLOUR: Vec3;
+/** A checked margin, in the terms the encoder wants: pixels, and 0..255. */
+export interface Margin {
+    size: number;
+    colour: {
+        r: number;
+        g: number;
+        b: number;
+    };
+}
+/**
+ * Apply the default and refuse anything that cannot be drawn, before a browser
+ * is launched — a margin is checked at the top of a render for the same reason
+ * `quality` is, so a mistake in it costs a millisecond rather than the whole
+ * trace it would otherwise be found after.
+ */
+export declare function resolveMargin(margin: MarginOptions | undefined): Margin | undefined;
+/**
+ * Mount an encoded image in its margin, and hand back the encoded result.
+ *
+ * The border is opaque whatever the image is: a colour is something to stand
+ * the plate on, so an `alpha` render comes back as a cut-out on that colour
+ * rather than as a cut-out with a transparent frame nobody would see.
+ */
+export declare function addMargin(image: Buffer, format: ImageFormat, margin: Margin, quality: number | undefined): Promise<{
+    data: Buffer;
+    width: number;
+    height: number;
+}>;

package/dist/margin.js

@@ -0,0 +1,84 @@
+import sharp from 'sharp';
+/** What every generated file gets when no colour is named: paper. */
+export const DEFAULT_MARGIN_COLOUR = [1, 1, 1];
+/**
+ * The quality each lossy encoder is asked for when the caller named none.
+ *
+ * A margin means the image is encoded twice — once by the canvas, once here —
+ * and the second encode has to be told what the first one did or a `.jpg` would
+ * quietly change quality the moment a border was added to it. These are the
+ * defaults `canvas.toDataURL()` uses, so an unasked-for margin costs one
+ * generation of a lossy codec and nothing else.
+ */
+const CANVAS_DEFAULT_QUALITY = {
+    png: undefined,
+    jpeg: 0.92,
+    webp: 0.8,
+};
+/** One colour component, as a byte. */
+function byte(value, index, colour) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`scenic-prism-playwright: \`margin.colour\` components must be between 0 and 1, ` +
+            `got ${value} at index ${index} of [${colour.join(', ')}].`);
+    }
+    return Math.round(value * 255);
+}
+/**
+ * Apply the default and refuse anything that cannot be drawn, before a browser
+ * is launched — a margin is checked at the top of a render for the same reason
+ * `quality` is, so a mistake in it costs a millisecond rather than the whole
+ * trace it would otherwise be found after.
+ */
+export function resolveMargin(margin) {
+    if (margin === undefined)
+        return undefined;
+    const { size, colour = DEFAULT_MARGIN_COLOUR } = margin;
+    if (!Number.isSafeInteger(size) || size < 1) {
+        throw new Error(`scenic-prism-playwright: \`margin.size\` must be a whole number of pixels ` +
+            `greater than zero, got ${size}.`);
+    }
+    if (!Array.isArray(colour) || colour.length !== 3) {
+        throw new Error(`scenic-prism-playwright: \`margin.colour\` must be an [r, g, b] triple, ` +
+            `got ${JSON.stringify(colour)}.`);
+    }
+    return {
+        size,
+        colour: {
+            r: byte(colour[0], 0, colour),
+            g: byte(colour[1], 1, colour),
+            b: byte(colour[2], 2, colour),
+        },
+    };
+}
+/** The encoder settings for a re-encode that must not change the format. */
+function encoderOptions(format, quality) {
+    const asked = quality ?? CANVAS_DEFAULT_QUALITY[format];
+    // PNG is lossless and `checkQuality` has already refused a quality alongside
+    // it, so there is nothing to carry across.
+    if (format === 'png' || asked === undefined)
+        return {};
+    // The canvas takes a fraction and every other encoder takes a percentage;
+    // 0 is not reachable, `checkQuality` having excluded it.
+    return { quality: Math.max(1, Math.round(asked * 100)) };
+}
+/**
+ * Mount an encoded image in its margin, and hand back the encoded result.
+ *
+ * The border is opaque whatever the image is: a colour is something to stand
+ * the plate on, so an `alpha` render comes back as a cut-out on that colour
+ * rather than as a cut-out with a transparent frame nobody would see.
+ */
+export async function addMargin(image, format, margin, quality) {
+    const { size, colour } = margin;
+    const { data, info } = await sharp(image)
+        .extend({
+        top: size,
+        bottom: size,
+        left: size,
+        right: size,
+        background: { ...colour, alpha: 1 },
+    })
+        .toFormat(format, encoderOptions(format, quality))
+        .toBuffer({ resolveWithObject: true });
+    return { data, width: info.width, height: info.height };
+}

package/dist/render.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The one-call surface. `renderToFile(scene, 'out.png')` opens a browser,
+ * traces the scene, writes the file and shuts everything down again — which is
+ * all most scripts ever want, and is exactly `openStudio()`, one render, and
+ * `close()`.
+ *
+ * Reach for {@link openStudio} instead when there is more than one image: the
+ * browser launch is the expensive part, and a studio pays it once.
+ */
+import type { FluentSceneSpec } from 'scenic-prism-fluent';
+import type { RenderOptions, RenderedImageData, SavedImage, StudioOptions } from './studio.js';
+/** Everything a standalone render takes: the render's options, and the browser's. */
+export interface HeadlessOptions extends RenderOptions, StudioOptions {
+}
+/**
+ * Path-trace `spec` and save it to `output`.
+ *
+ * ```ts
+ * import { backgrounds, materials, sphere } from 'scenic-prism-fluent';
+ * import { renderToFile } from 'scenic-prism-playwright';
+ *
+ * await renderToFile(
+ *   { scene: sphere(1).paint(materials.chrome), background: backgrounds.dusk },
+ *   'renders/sphere.png',
+ *   { size: 1200, maxFrames: 900, seed: 7 },
+ * );
+ * ```
+ *
+ * The encoding comes from the file's extension — `.png`, `.jpg`, `.jpeg` or
+ * `.webp` — unless `format` says otherwise, and any directories in the path are
+ * created. Give `seed` to make the image reproducible; without one the sample
+ * sequence is random, so two runs of the same scene differ in their noise. The
+ * render takes the machine's GPU where there is one — add `gpu: false` for
+ * software rasterisation, which is what makes two *machines* agree as well.
+ */
+export declare function renderToFile(spec: FluentSceneSpec, output: string, options?: HeadlessOptions): Promise<SavedImage>;
+/**
+ * The same render, handed back as bytes rather than written. `format` defaults
+ * to `png` here, there being no filename to read it from.
+ */
+export declare function renderToBuffer(spec: FluentSceneSpec, options?: HeadlessOptions): Promise<RenderedImageData>;

package/dist/render.js

@@ -0,0 +1,42 @@
+import { openStudio } from "./studio.js";
+/** Open a studio, run one job in it, and close it however the job ends. */
+async function once(options, job) {
+    const studio = await openStudio(options);
+    try {
+        return await job(studio);
+    }
+    finally {
+        await studio.close();
+    }
+}
+/**
+ * Path-trace `spec` and save it to `output`.
+ *
+ * ```ts
+ * import { backgrounds, materials, sphere } from 'scenic-prism-fluent';
+ * import { renderToFile } from 'scenic-prism-playwright';
+ *
+ * await renderToFile(
+ *   { scene: sphere(1).paint(materials.chrome), background: backgrounds.dusk },
+ *   'renders/sphere.png',
+ *   { size: 1200, maxFrames: 900, seed: 7 },
+ * );
+ * ```
+ *
+ * The encoding comes from the file's extension — `.png`, `.jpg`, `.jpeg` or
+ * `.webp` — unless `format` says otherwise, and any directories in the path are
+ * created. Give `seed` to make the image reproducible; without one the sample
+ * sequence is random, so two runs of the same scene differ in their noise. The
+ * render takes the machine's GPU where there is one — add `gpu: false` for
+ * software rasterisation, which is what makes two *machines* agree as well.
+ */
+export async function renderToFile(spec, output, options = {}) {
+    return once(options, (studio) => studio.renderToFile(spec, output, options));
+}
+/**
+ * The same render, handed back as bytes rather than written. `format` defaults
+ * to `png` here, there being no filename to read it from.
+ */
+export async function renderToBuffer(spec, options = {}) {
+    return once(options, (studio) => studio.renderToBuffer(spec, options));
+}

package/dist/studio.d.ts

@@ -0,0 +1,251 @@
+import type { Browser, LaunchOptions } from 'playwright';
+import type { ColorSpace, FluentSceneSpec, SceneSpec, ToneCurve } from 'scenic-prism-fluent';
+import type { ImageFormat } from './image.js';
+import type { MarginOptions } from './margin.js';
+/**
+ * How hard to try for the machine's GPU.
+ *
+ * - `'auto'` (the default) asks for hardware and takes SwiftShader when there
+ *   is none, so a laptop is fast and a build container still works.
+ * - `true` insists on hardware: a machine without it fails rather than
+ *   quietly spending twenty minutes on what should have taken one.
+ * - `false` is software everywhere, which is the reproducible one — the same
+ *   scene and `seed` then give the same pixels on every machine.
+ */
+export type GpuPreference = boolean | 'auto';
+/**
+ * Software rendering, asked for explicitly: SwiftShader's WebGPU adapter and
+ * nothing else, whatever the machine has. This is what `gpu: false` launches
+ * with, and it is the only setting under which two machines agree pixel for
+ * pixel — a GPU and a software rasteriser round differently, so the same
+ * `seed` on each gives images that look identical and hash differently.
+ */
+export declare const SOFTWARE_BROWSER_ARGS: readonly string[];
+/**
+ * Hardware and no substitute: what `gpu: true` launches with. Chromium is asked
+ * to leave the software fallback out altogether — though that is not what
+ * enforces `true`, since a browser is entitled to hand out its fallback adapter
+ * anyway. What enforces it is {@link requireHardware}, which asks a page which
+ * adapter it would actually trace with.
+ */
+export declare const GPU_BROWSER_ARGS: readonly string[];
+/**
+ * What a launch takes by default: the hardware switches, and permission to fall
+ * back to SwiftShader rather than the instruction not to. A browser with no GPU
+ * to offer hands a page SwiftShader's adapter by itself, which is why `'auto'`
+ * needs no probe of its own — the browser answers the question by starting.
+ *
+ * Chromium takes the last occurrence of a switch, so anything passed in
+ * `launch.args` still overrides what is here.
+ */
+export declare const DEFAULT_BROWSER_ARGS: readonly string[];
+/**
+ * The launches to try, in order, for a preference — each one falling back to
+ * the next only if Chromium refuses to start at all.
+ *
+ * A caller who named a `channel` or an `executablePath` has said which binary
+ * to run, so that one is left alone and there is nothing to fall back to.
+ */
+export declare function launchPlan(gpu: GpuPreference, launch?: LaunchOptions): LaunchOptions[];
+/** What a page says about the adapter it traces with. */
+export interface AdapterReport {
+    /** Vendor, architecture and whatever else the adapter will say, in a line. */
+    renderer: string;
+    /** Whether the browser itself calls it a fallback — a software one. */
+    fallback: boolean;
+}
+/** Whether a reported adapter is a software one. */
+export declare function isSoftwareAdapter({ renderer, fallback }: AdapterReport): boolean;
+/**
+ * How long a single render is given before it is abandoned. Generous on
+ * purpose: a thousand samples of a glassy scene at 1024² is minutes of software
+ * path tracing, and a timeout that fires on a render that was going to finish
+ * is worse than one that fires late.
+ */
+export declare const DEFAULT_TIMEOUT = 300000;
+/** The renderer's own knobs, as far as a still image cares about them. */
+export interface TraceOptions {
+    /** Square backing resolution in pixels. 1024 by default. */
+    size?: number;
+    /** Backing-store width in pixels, when the image is not square. */
+    width?: number;
+    /** Backing-store height in pixels, when the image is not square. */
+    height?: number;
+    /** Samples per pixel to accumulate before saving. 1200 by default. */
+    maxFrames?: number;
+    /** Light-bounce budget. 6 by default; glass and metal reward more. */
+    bounces?: number;
+    /**
+     * The curve that brings the traced light into display range: `'aces'` (the
+     * default), `'reinhard'` or `'linear'`.
+     */
+    tone?: ToneCurve;
+    /**
+     * Exposure in stops, applied before the tone curve — `-1` is half as bright,
+     * `+2` four times. What to reach for when a plate comes out too bright, since
+     * it moves the whole image rather than the colours in the scene one by one.
+     */
+    exposure?: number;
+    /**
+     * Trace onto a transparent background instead of onto the environment, so
+     * the image saves with a cut-out rather than a sky behind it. Wants a format
+     * that has an alpha channel to save into — `png` or `webp`, not `jpeg`.
+     */
+    alpha?: boolean;
+    /**
+     * The colour space to trace in: `'srgb'` (the default) or `'display-p3'`,
+     * where the browser has it. A P3 image is saved tagged as one.
+     */
+    colorSpace?: ColorSpace;
+    /** Fix the sample sequence, for a byte-for-byte reproducible image. */
+    seed?: number;
+}
+/** Everything a single render takes, on top of the scene itself. */
+export interface RenderOptions extends TraceOptions {
+    /** Encoding to save. Taken from the output file's extension by default. */
+    format?: ImageFormat;
+    /** Encoder quality in (0, 1], for `jpeg` and `webp`. */
+    quality?: number;
+    /**
+     * A border of flat colour around the finished image — `{ size }` in pixels,
+     * with an optional `colour` that is white if left out.
+     *
+     * It is added after the trace rather than before it: the page is served and
+     * the canvas is sized exactly as they would be without one, so the scene
+     * comes out identical and lands in a larger file. A margin on a `jpeg` or a
+     * `webp` costs one further generation of the encoder, at whatever `quality`
+     * the render was saved at.
+     */
+    margin?: MarginOptions;
+    /** Milliseconds before the render is abandoned. 300000 by default. */
+    timeout?: number;
+    /** Called in this process after every accumulated frame. */
+    onProgress?: (frames: number, total: number) => void;
+}
+/** What a finished render reports about itself. */
+export interface RenderedImage {
+    /** The encoding actually written. */
+    format: ImageFormat;
+    /** Width of the saved image in pixels, including any `margin`. */
+    width: number;
+    /** Height of the saved image in pixels, including any `margin`. */
+    height: number;
+    /** Samples per pixel that were accumulated. */
+    frames: number;
+    /** Size of the encoded image in bytes. */
+    bytes: number;
+    /**
+     * What WebGPU reported as the adapter behind the trace — a graphics card's
+     * vendor and architecture (`apple metal-3`), or a software one
+     * (`google swiftshader`). Empty if the browser would not say.
+     */
+    renderer: string;
+    /** Whether that adapter was hardware. False for SwiftShader, and if unknown. */
+    accelerated: boolean;
+    /** The colour space the image was traced and saved in. */
+    colorSpace: ColorSpace;
+}
+/** A render that went to memory. */
+export interface RenderedImageData extends RenderedImage {
+    /** The encoded image. */
+    data: Buffer;
+}
+/** A render that went to disk. */
+export interface SavedImage extends RenderedImage {
+    /** The absolute path written. */
+    path: string;
+}
+/** How a studio is opened. */
+export interface StudioOptions {
+    /**
+     * An already-running browser to draw in. Given one, the studio never launches
+     * or closes anything — useful inside a Playwright test that already has a
+     * browser, and the seam this package's own tests drive it through.
+     */
+    browser?: Browser;
+    /**
+     * Whether to render on the machine's GPU. `'auto'` by default: hardware when
+     * this machine has some, SwiftShader when it does not. Pass `false` for
+     * software everywhere, which is what makes an image reproducible across
+     * machines, or `true` to fail rather than fall back.
+     */
+    gpu?: GpuPreference;
+    /** Passed to `chromium.launch()`, on top of {@link DEFAULT_BROWSER_ARGS}. */
+    launch?: LaunchOptions;
+    /**
+     * The `scenic-prism` package root to serve to the page. Found beside the
+     * installed `scenic-prism-fluent` by default, which is the copy the scenes
+     * handed in were built with.
+     */
+    libraryRoot?: string;
+    /** Default timeout in milliseconds for the renders in this studio. */
+    timeout?: number;
+}
+/** A browser held open across several renders. */
+export interface Studio {
+    /** Trace a scene and write it to `output`, creating directories as needed. */
+    renderToFile(spec: FluentSceneSpec, output: string, options?: RenderOptions): Promise<SavedImage>;
+    /** Trace a scene and return the encoded bytes. `format` defaults to png. */
+    renderToBuffer(spec: FluentSceneSpec, options?: RenderOptions): Promise<RenderedImageData>;
+    /** Close the browser, unless it was handed in. */
+    close(): Promise<void>;
+}
+/** What the page is asked to do, as plain data — it crosses a process. */
+export interface TraceJob {
+    spec: SceneSpec;
+    trace: TraceOptions;
+    mimeType: string;
+    quality?: number;
+    reportProgress: boolean;
+    /** The globals the traced function reads, since it can close over nothing. */
+    library: string;
+    binding: string;
+}
+/** What it answers with. */
+export interface TraceResult {
+    dataUrl: string;
+    width: number;
+    height: number;
+    frames: number;
+    /** What WebGPU said drew it, so this process can report what it got. */
+    adapter: AdapterReport;
+    colorSpace: ColorSpace;
+}
+/**
+ * The whole of the in-page work, and the only code here that runs in the
+ * browser. It takes the library the document loaded, traces until the
+ * accumulation finishes on its own, and reads the finished image back.
+ *
+ * Read back from the render rather than from the canvas: a WebGPU canvas does
+ * not keep what was drawn into it once that has been shown, so the render is
+ * started with `retain` and asked for its pixels, which are then encoded
+ * through a 2D canvas — the one thing in a browser that turns pixels into a
+ * PNG, a JPEG or a WebP. The render itself goes to an `OffscreenCanvas`, which
+ * the library draws into exactly as it would a canvas on a page.
+ *
+ * This function is sent across as source, so it can close over nothing: every
+ * value it needs, including the names of the two globals, arrives in `job`.
+ *
+ * Exported for `studio.test.ts` alone — `index.ts` does not re-export it, so it
+ * is no part of the package's surface. Being sent across as source is exactly
+ * why it is worth calling directly: nothing else here would catch a mistake in
+ * it before a browser did.
+ */
+export declare function traceInPage(job: TraceJob): Promise<TraceResult>;
+/**
+ * Which adapter a page would trace with, asked before anything is traced. Sent
+ * across as source like {@link traceInPage}, so it closes over nothing and
+ * reads no globals. `null` is a page with no WebGPU adapter at all.
+ *
+ * Exported for the tests on the same terms as {@link traceInPage}.
+ */
+export declare function probeAdapterInPage(): Promise<AdapterReport | null>;
+/**
+ * Open a browser and keep it open. Every scene rendered through the returned
+ * studio shares it, which is most of the cost of the first image and all of the
+ * cost of the rest. Close it when the batch is done.
+ *
+ * The browser is asked for the machine's GPU unless `gpu` says otherwise, and
+ * takes SwiftShader wherever there is none to have. See {@link GpuPreference}.
+ */
+export declare function openStudio(options?: StudioOptions): Promise<Studio>;