@shotkit/shotium 0.2.0 → 0.3.0

package/dist/engine-Xe7nH-1i.js

@@ -1,267 +0,0 @@
-import { createRequire } from "node:module";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import crypto from "node:crypto";
-import os from "node:os";
-
-//#region src/lib/config.ts
-function resolveStartOptions(options = {}) {
-	return {
-		cacheDir: options.cacheDir ?? null,
-		userAgent: options.userAgent,
-		resourceDir: options.resourceDir
-	};
-}
-
-//#endregion
-//#region src/lib/endpoint.ts
-function endpointKey(options) {
-	if (options.name) return String(options.name);
-	const identity = JSON.stringify([
-		options.cacheDir === null || options.cacheDir === void 0 ? null : path.resolve(options.cacheDir),
-		options.userAgent ?? null,
-		options.resourceDir ? path.resolve(options.resourceDir) : null
-	]);
-	return crypto.createHash("sha256").update(identity).digest("hex").slice(0, 16);
-}
-function endpointFor(options = {}) {
-	if (options.endpoint) return options.endpoint;
-	if (process.env.SHOTIUM_ENDPOINT) return process.env.SHOTIUM_ENDPOINT;
-	const key = endpointKey(options);
-	if (process.platform === "win32") return `\\\\.\\pipe\\shotium-${key}`;
-	const uid = typeof process.getuid === "function" ? process.getuid() : 0;
-	return path.join(os.tmpdir(), `shotium-${uid}-${key}.sock`);
-}
-
-//#endregion
-//#region src/lib/protocol.ts
-const HEADER_BYTES = 4;
-function encodeFrame(payload) {
-	const header = Buffer.allocUnsafe(4);
-	header.writeUInt32LE(payload.length, 0);
-	return Buffer.concat([header, payload]);
-}
-var FrameReader = class {
-	buffer = Buffer.alloc(0);
-	push(chunk) {
-		this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
-	}
-	next() {
-		if (this.buffer.length < 4) return null;
-		const length = this.buffer.readUInt32LE(0);
-		if (this.buffer.length < 4 + length) return null;
-		const frame = this.buffer.subarray(4, 4 + length);
-		this.buffer = this.buffer.subarray(4 + length);
-		return frame;
-	}
-};
-
-//#endregion
-//#region src/lib/request.ts
-const DEFAULT_TIMEOUT_MS = 3e4;
-const WIRE_FIELDS = /* @__PURE__ */ new Set([
-	"file",
-	"type",
-	"fullPage",
-	"selector",
-	"quality",
-	"scale",
-	"omitBackground",
-	"path",
-	"pageGotoParams",
-	"clip",
-	"viewport",
-	"allowFileAccess"
-]);
-function toRequest(options) {
-	if (!options || typeof options !== "object") throw new TypeError("shotium: screenshot(options) needs an object");
-	if (typeof options.file !== "string" || options.file.length === 0) throw new TypeError("shotium: options.file is required");
-	const request = {};
-	for (const [key, value] of Object.entries(options)) {
-		if (value === void 0) continue;
-		if (!WIRE_FIELDS.has(key)) throw new TypeError(`shotium: unknown option "${key}"`);
-		request[key] = value;
-	}
-	if (request.viewport) {
-		const { width, height } = request.viewport;
-		delete request.viewport;
-		if (width !== void 0) request.width = width;
-		if (height !== void 0) request.height = height;
-	}
-	return request;
-}
-function timeoutFor(options) {
-	const timeout = options.pageGotoParams && options.pageGotoParams.timeout;
-	return typeof timeout === "number" ? timeout : DEFAULT_TIMEOUT_MS;
-}
-
-//#endregion
-//#region src/lib/platform.ts
-const require$1 = createRequire(import.meta.url);
-const PACKAGES = {
-	"win32-x64": "@shotkit/shotium-win32-x64",
-	"win32-arm64": "@shotkit/shotium-win32-arm64",
-	"darwin-x64": "@shotkit/shotium-darwin-x64",
-	"darwin-arm64": "@shotkit/shotium-darwin-arm64",
-	"linux-x64": "@shotkit/shotium-linux-x64",
-	"linux-arm64": "@shotkit/shotium-linux-arm64"
-};
-function packageName(platform = process.platform, arch = process.arch) {
-	return PACKAGES[`${platform}-${arch}`] ?? null;
-}
-function packageDir() {
-	const name = packageName();
-	if (!name) return null;
-	try {
-		return path.dirname(require$1.resolve(`${name}/package.json`));
-	} catch {
-		return null;
-	}
-}
-
-//#endregion
-//#region src/lib/binding.ts
-const require = createRequire(import.meta.url);
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-function candidates() {
-	const found = [];
-	const dir = packageDir();
-	if (dir) found.push(path.join(dir, "shotium.node"));
-	found.push(path.join(HERE, "..", "native", "build", "Release", "shotium.node"));
-	return found;
-}
-let binding = null;
-let loadedFrom = null;
-/**
-* The addon, loaded once. Throws if there is none for this platform, which is
-* the only failure this package cannot work around: there is nothing else to
-* fall back to.
-*/
-function load() {
-	if (binding) return binding;
-	const tried = candidates();
-	for (const candidate of tried) {
-		if (!fs.existsSync(candidate)) continue;
-		binding = require(candidate);
-		loadedFrom = path.dirname(candidate);
-		return binding;
-	}
-	const expected = packageName();
-	throw new Error(`shotium: no engine for this platform.
-  looked in:\n    ${tried.join("\n    ")}\n` + (expected ? `  It ships in ${expected}, which npm installs as an optional dependency of this package. If the install skipped optional dependencies, it is not there.
-` : `  There is no build for ${process.platform}-${process.arch}.\n`));
-}
-/**
-* The directory the addon came from, or null before the first load(). The
-* resource packs ship beside it, which is what this is for.
-*/
-function directory() {
-	return loadedFrom;
-}
-
-//#endregion
-//#region src/lib/engine.ts
-let startedInThisProcess = false;
-/**
-* Blink, in this process, and the queue in front of it.
-*
-* There is one renderer and there is no way to have two. Blink is a
-* process-wide singleton: it is initialised once, there is no path to a second
-* one, and `worker_threads` do not change that because they share the process.
-* So captures are serialised however many callers there are, and a program
-* that wants four at once wants four processes.
-*
-* The queue is not about fairness. Each capture occupies a libuv thread pool
-* thread for as long as the render takes, and there are four of those by
-* default, shared with fs and dns -- so letting four screenshots go at once
-* would stall the host's file reads for a fifth of a second at a time while
-* gaining nothing, since the engine serialises them anyway.
-*/
-var Engine = class {
-	handle = null;
-	stopped = false;
-	tail = Promise.resolve();
-	get running() {
-		return this.handle !== null;
-	}
-	/**
-	* Starts the engine. Safe to call twice; the second call is a no-op, so that
-	* library code can call it defensively.
-	*
-	* Not safe to call after `stop()`, and not because of anything here: Blink
-	* starts once per process and cannot be restarted. Another engine means
-	* another process.
-	*/
-	start(options = {}) {
-		if (this.handle) return this;
-		if (this.stopped) throw new Error("shotium: this engine was stopped, and Blink cannot be started again in a process that has already run it. Start another process, or keep the engine up between screenshots.");
-		if (startedInThisProcess) throw new Error("shotium: an engine has already run in this process. Blink is a process-wide singleton -- there is one per process, ever -- so a second Runtime cannot have one. Use the shared `runtime`, or run another process.");
-		const native = load();
-		const resolved = resolveStartOptions(options);
-		const engineOptions = {};
-		if (resolved.cacheDir !== null) engineOptions.cacheDir = resolved.cacheDir;
-		if (resolved.userAgent !== void 0) engineOptions.userAgent = resolved.userAgent;
-		engineOptions.resourceDir = resolved.resourceDir ?? directory();
-		this.handle = native.create(JSON.stringify(engineOptions));
-		startedInThisProcess = true;
-		return this;
-	}
-	/**
-	* Stops the engine, after whatever is queued.
-	*
-	* Final for this process: see the note above. A program that will want
-	* another screenshot later should leave the engine up and call `purge()`
-	* instead, which hands back the memory without giving up the engine.
-	*/
-	async stop() {
-		if (!this.handle) return;
-		this.stopped = true;
-		const handle = this.handle;
-		this.handle = null;
-		await this.tail.catch(() => {});
-		load().destroy(handle);
-	}
-	/**
-	* Hands back what the engine is holding but can rebuild.
-	* `releaseWorkingSet` additionally asks the OS for the pages, which the next
-	* screenshot pays back in soft faults -- worth it when there may not be a
-	* next one soon.
-	*
-	* The daemon does this for itself on a timer because it can watch its own
-	* request stream go quiet. Here the queue belongs to the caller, so the
-	* caller is the one who knows a batch has ended.
-	*/
-	purge({ releaseWorkingSet = false } = {}) {
-		if (!this.handle) return;
-		load().purge(this.handle, releaseWorkingSet);
-	}
-	/**
-	* Renders one screenshot. Resolves to the encoded image, or to `null` when
-	* `path` was given and the engine wrote the file itself.
-	*/
-	async screenshot(options) {
-		return this.capture(toRequest(options));
-	}
-	/**
-	* The same, for a request that is already in wire form.
-	*
-	* The daemon reads these off a socket, where they arrived having been
-	* validated by the client that sent them. Re-deriving one from
-	* ScreenshotOptions would mean the daemon validating a request it cannot see
-	* the original of, and rejecting fields a newer client legitimately sent.
-	*/
-	async capture(request) {
-		if (!this.handle) this.start();
-		const handle = this.handle;
-		const native = load();
-		const result = this.tail.catch(() => {}).then(() => native.capture(handle, JSON.stringify(request)));
-		this.tail = result.catch(() => {});
-		const image = await result;
-		return request.path ? null : image;
-	}
-};
-
-//#endregion
-export { encodeFrame as a, FrameReader as i, timeoutFor as n, endpointFor as o, toRequest as r, resolveStartOptions as s, Engine as t };
-//# sourceMappingURL=engine-Xe7nH-1i.js.map

package/dist/engine-Xe7nH-1i.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"engine-Xe7nH-1i.js","names":["require","platformPackage.packageDir","platformPackage.packageName","binding.load","binding.directory"],"sources":["../src/lib/config.ts","../src/lib/endpoint.ts","../src/lib/protocol.ts","../src/lib/request.ts","../src/lib/platform.ts","../src/lib/binding.ts","../src/lib/engine.ts"],"sourcesContent":["import type {StartOptions} from '../types.js';\n\n// StartOptions with every hole filled in. `cacheDir` is still nullable here\n// because null is an answer -- \"no disk cache\" -- and not an absent one.\nexport interface ResolvedStartOptions {\n  cacheDir: string|null;\n  userAgent?: string;\n  resourceDir?: string;\n}\n\n// The one place that decides what \"no options\" means.\n//\n// It is shared rather than duplicated because the daemon's address is a hash of\n// its configuration: if two callers filled in defaults even slightly\n// differently, one would compute an address no daemon is listening on and\n// start a second engine next to the first one that was already warm. See\n// endpoint.ts.\n//\n// The default for `cacheDir` is null -- no disk cache. A program holding the\n// engine is often short-lived, and a cache it never reads twice is a directory\n// it leaves behind. The daemon, which is the case where a cache does pay for\n// itself, is also the case where the caller is already passing options.\nfunction resolveStartOptions(options: StartOptions = {}): ResolvedStartOptions {\n  return {\n    cacheDir: options.cacheDir ?? null,\n    userAgent: options.userAgent,\n    resourceDir: options.resourceDir,\n  };\n}\n\nexport {resolveStartOptions};\n","import crypto from 'node:crypto';\nimport os from 'node:os';\nimport path from 'node:path';\n\n// What endpointFor() needs to know: a resolved configuration, plus the two\n// ways of overriding the address it would derive from one.\nexport interface EndpointOptions {\n  cacheDir?: string|null;\n  userAgent?: string;\n  resourceDir?: string;\n  name?: string;\n  endpoint?: string;\n}\n\n// Where a daemon listens, derived from what it was asked to be.\n//\n// The address is a hash of the configuration -- cache root, user agent,\n// resource directory -- rather than a fixed name, because attaching to\n// whatever daemon happens to be up would mean rendering with someone else's\n// settings. Two configurations are two daemons; the same configuration, from\n// any process, is one.\n//\n// Every field of EndpointOptions is optional, so nothing here fails to compile\n// when a field is dropped from the configuration -- it just stops being part\n// of the identity, and every caller collapses onto one address. That happened\n// once, when the worker pool went away and this was left hashing three fields\n// that no longer existed. If a field is added to StartOptions and it changes\n// what the engine renders, it belongs in the array below.\n//\n// A caller who wants a daemon by name instead of by configuration passes\n// `name`, which replaces the hash. That is the escape hatch for a service that\n// starts its daemon deliberately and wants clients to find it without\n// repeating the configuration.\nfunction endpointKey(options: EndpointOptions): string {\n  if (options.name) {\n    return String(options.name);\n  }\n  const identity = JSON.stringify([\n    options.cacheDir === null || options.cacheDir === undefined ?\n        null :\n        path.resolve(options.cacheDir),\n    options.userAgent ?? null,\n    options.resourceDir ? path.resolve(options.resourceDir) : null,\n  ]);\n  return crypto.createHash('sha256').update(identity).digest('hex').slice(0, 16);\n}\n\n// Windows has named pipes and no filesystem sockets; POSIX has the reverse.\n// Both are net.connect() addresses, which is the only reason the rest of the\n// daemon can ignore the difference.\n//\n// The pipe namespace is per-machine but the socket path is per-user, so the\n// uid goes in the POSIX name to keep two users on one host from colliding on a\n// path only one of them can open.\nfunction endpointFor(options: EndpointOptions = {}): string {\n  if (options.endpoint) {\n    return options.endpoint;\n  }\n  if (process.env.SHOTIUM_ENDPOINT) {\n    return process.env.SHOTIUM_ENDPOINT;\n  }\n  const key = endpointKey(options);\n  if (process.platform === 'win32') {\n    return `\\\\\\\\.\\\\pipe\\\\shotium-${key}`;\n  }\n  const uid = typeof process.getuid === 'function' ? process.getuid() : 0;\n  return path.join(os.tmpdir(), `shotium-${uid}-${key}.sock`);\n}\n\nexport {endpointFor, endpointKey};\n","// The wire format shotium.exe --serve speaks, in both directions: a 4-byte\n// little-endian length followed by that many bytes.\n//\n// Length-prefixed rather than line-delimited because the payload is binary and\n// a newline inside a PNG is not a message boundary. See shot/shot_server.h for\n// the same description from the other end.\n//\n//   ->  [len][{\"file\":\"...\",\"width\":1248,...}]\n//   <-  [len][{\"ok\":true,\"bytes\":97756}]  [len][<PNG bytes>]\n//   <-  [len][{\"ok\":false,\"error\":\"...\"}] [0]\n\nconst HEADER_BYTES = 4;\n\nfunction encodeFrame(payload: Buffer): Buffer {\n  const header = Buffer.allocUnsafe(HEADER_BYTES);\n  header.writeUInt32LE(payload.length, 0);\n  return Buffer.concat([header, payload]);\n}\n\nfunction encodeRequest(request: unknown): Buffer {\n  return encodeFrame(Buffer.from(JSON.stringify(request), 'utf8'));\n}\n\n// Reassembles frames out of whatever sizes the pipe hands over.\n//\n// A stream is not a sequence of messages: one read can carry half a header, or\n// three responses and the start of a fourth. Everything downstream assumes\n// whole frames, so this is the only place that has to know that.\nclass FrameReader {\n  private buffer: Buffer = Buffer.alloc(0);\n\n  push(chunk: Buffer): void {\n    this.buffer = this.buffer.length === 0 ?\n        chunk :\n        Buffer.concat([this.buffer, chunk]);\n  }\n\n  // The next complete frame, or null when there is not one yet.\n  next(): Buffer|null {\n    if (this.buffer.length < HEADER_BYTES) {\n      return null;\n    }\n    const length = this.buffer.readUInt32LE(0);\n    if (this.buffer.length < HEADER_BYTES + length) {\n      return null;\n    }\n    const frame = this.buffer.subarray(HEADER_BYTES, HEADER_BYTES + length);\n    this.buffer = this.buffer.subarray(HEADER_BYTES + length);\n    return frame;\n  }\n}\n\nexport {HEADER_BYTES, encodeFrame, encodeRequest, FrameReader};\n","import type {Clip, PageGotoParams, ScreenshotOptions} from '../types.js';\n\nconst DEFAULT_TIMEOUT_MS = 30000;\n\n// What actually goes down the pipe: ScreenshotOptions with the viewport\n// flattened -- see toRequest below for why.\nexport interface WireRequest {\n  file: string;\n  type?: 'png'|'jpeg'|'webp';\n  fullPage?: boolean;\n  selector?: string;\n  quality?: number;\n  scale?: number;\n  omitBackground?: boolean;\n  path?: string;\n  pageGotoParams?: PageGotoParams;\n  clip?: Clip;\n  allowFileAccess?: boolean;\n  width?: number;\n  height?: number;\n}\n\n// Everything the worker understands, and nothing else. An unknown field is a\n// typo, and a typo that is silently dropped is a screenshot that quietly\n// ignored what was asked for -- so this rejects rather than filters.\n//\n// It is a runtime check even though the argument has a type, because the\n// argument having a type says nothing about a caller who is not compiled\n// against it: a JavaScript program, or a JSON body from somewhere else.\nconst WIRE_FIELDS = new Set([\n  'file',\n  'type',\n  'fullPage',\n  'selector',\n  'quality',\n  'scale',\n  'omitBackground',\n  'path',\n  'pageGotoParams',\n  'clip',\n  'viewport',\n  'allowFileAccess',\n]);\n\n// One ScreenshotOptions, checked and flattened into what goes on the wire.\n//\n// It lives here rather than in index.ts because the engine in this process and\n// the daemon both send it: a request that is valid through one entry point and\n// rejected through the other would be a difference nobody asked for.\nfunction toRequest(options: ScreenshotOptions): WireRequest {\n  if (!options || typeof options !== 'object') {\n    throw new TypeError('shotium: screenshot(options) needs an object');\n  }\n  if (typeof options.file !== 'string' || options.file.length === 0) {\n    throw new TypeError('shotium: options.file is required');\n  }\n\n  const request: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(options)) {\n    if (value === undefined) {\n      continue;\n    }\n    if (!WIRE_FIELDS.has(key)) {\n      throw new TypeError(`shotium: unknown option \"${key}\"`);\n    }\n    request[key] = value;\n  }\n\n  // The viewport is flattened because the worker takes width and height at the\n  // top level: it is one screenshot's frame, not a nested object on the wire.\n  if (request.viewport) {\n    const {width, height} = request.viewport as {\n      width?: number,\n      height?: number,\n    };\n    delete request.viewport;\n    if (width !== undefined) {\n      request.width = width;\n    }\n    if (height !== undefined) {\n      request.height = height;\n    }\n  }\n  return request as unknown as WireRequest;\n}\n\nfunction timeoutFor(options: ScreenshotOptions): number {\n  const timeout = options.pageGotoParams && options.pageGotoParams.timeout;\n  return typeof timeout === 'number' ? timeout : DEFAULT_TIMEOUT_MS;\n}\n\nexport {\n  DEFAULT_TIMEOUT_MS,\n  WIRE_FIELDS,\n  timeoutFor,\n  toRequest,\n};\n","import {createRequire} from 'node:module';\nimport path from 'node:path';\n\n// require.resolve is the resolver, and ESM has no synchronous equivalent\n// that answers for a package that may not be installed at all.\nconst require = createRequire(import.meta.url);\n\n// Which package carries the engine for this machine.\n//\n// The engine is not in this package and cannot be: it is a Chromium build,\n// 41 MB per platform and architecture, six of them, and `npm install` is never\n// going to produce one. So the bytes live in six packages of their own and\n// this one depends on all six as optionalDependencies with `os` and `cpu` set,\n// which is npm's way of saying \"install the one that matches this machine and\n// skip the other five\". A machine nobody builds for installs none of them and\n// still gets a working package -- it just has to be pointed at an engine.\n//\n// The alternative, a postinstall script that downloads a tarball, was not\n// chosen. It defeats a lockfile, which is supposed to pin what you get; it\n// fails behind a registry mirror, which is the one place a large dependency\n// most needs to work; and it runs code at install time in exchange for saving\n// nothing that npm was not already doing.\n//\n// Key and name are both `${process.platform}-${process.arch}`, so the table is\n// the identity map with a prefix on it. That is deliberate: the value npm\n// matches `os` and `cpu` against is process.platform, and a package named for\n// anything else makes the reader hold two spellings of one machine in their\n// head. It is also what every other package of this shape does -- esbuild,\n// swc, lightningcss all publish darwin-arm64 and win32-x64.\n//\n// The release archives spell it win/mac instead -- shotium-mac-arm64.7z --\n// and that is not going to change either. They are downloaded by people, and\n// `mac` is what people call it. So the two spellings do differ, in the one\n// place where each is right: the registry gets node's, the download page gets\n// the reader's.\nconst PACKAGES: Readonly<Record<string, string>> = {\n  'win32-x64': '@shotkit/shotium-win32-x64',\n  'win32-arm64': '@shotkit/shotium-win32-arm64',\n  'darwin-x64': '@shotkit/shotium-darwin-x64',\n  'darwin-arm64': '@shotkit/shotium-darwin-arm64',\n  'linux-x64': '@shotkit/shotium-linux-x64',\n  'linux-arm64': '@shotkit/shotium-linux-arm64',\n};\n\nfunction packageName(\n    platform: string = process.platform,\n    arch: string = process.arch): string|null {\n  return PACKAGES[`${platform}-${arch}`] ?? null;\n}\n\n// Where the matching platform package unpacked, or null if it is not installed.\n//\n// require.resolve rather than a path built from the module's own location: the\n// package can be hoisted to a workspace root, nested under this one, or left\n// in a pnpm store with a symlink pointing at it, and the resolver is the only\n// thing that knows which of those happened.\nfunction packageDir(): string|null {\n  const name = packageName();\n  if (!name) {\n    return null;\n  }\n  try {\n    return path.dirname(require.resolve(`${name}/package.json`));\n  } catch {\n    return null;\n  }\n}\n\nexport {PACKAGES, packageDir, packageName};\n","import fs from 'node:fs';\nimport {createRequire} from 'node:module';\nimport path from 'node:path';\nimport {fileURLToPath} from 'node:url';\n\nimport * as platformPackage from './platform.js';\n\n// A .node addon is a CommonJS artefact: there is no ESM loader for one.\nconst require = createRequire(import.meta.url);\n\n// ESM has no __dirname. This is the same thing, from the module's own URL.\nconst HERE = path.dirname(fileURLToPath(import.meta.url));\n\n/**\n * The engine handle the addon hands back. Opaque on purpose: everything that\n * can be done with it is a call on the binding below.\n */\nexport type Engine = unknown;\n\n/** What native/binding.cc exports. See shot/shot_api.h for the C ABI. */\nexport interface NativeBinding {\n  create(optionsJson: string): Engine;\n  destroy(engine: Engine): void;\n  purge(engine: Engine, releaseWorkingSet: boolean): void;\n  capture(engine: Engine, requestJson: string): Promise<Buffer>;\n}\n\n// Where the addon and the library beside it live.\n//\n// The platform package is what ships -- the .node sits next to the shared\n// library it is linked against, which is the whole reason the two travel in\n// one package rather than two. native/build/Release is where node-gyp puts a\n// local build; it exists in a checkout and not in an install, so the two never\n// compete in practice. Both paths are relative to this file's build output,\n// which is one directory below the package root.\nfunction candidates(): string[] {\n  const found: string[] = [];\n  const dir = platformPackage.packageDir();\n  if (dir) {\n    found.push(path.join(dir, 'shotium.node'));\n  }\n  found.push(\n      path.join(HERE, '..', 'native', 'build', 'Release', 'shotium.node'));\n  return found;\n}\n\nlet binding: NativeBinding|null = null;\nlet loadedFrom: string|null = null;\n\n/**\n * The addon, loaded once. Throws if there is none for this platform, which is\n * the only failure this package cannot work around: there is nothing else to\n * fall back to.\n */\nexport function load(): NativeBinding {\n  if (binding) {\n    return binding;\n  }\n  const tried = candidates();\n  for (const candidate of tried) {\n    if (!fs.existsSync(candidate)) {\n      continue;\n    }\n    // Not wrapped in a try: a .node that is there and will not load is a\n    // broken installation, and the loader's own message -- a missing\n    // dependency, an architecture mismatch -- says more than anything that\n    // could be substituted for it.\n    binding = require(candidate) as NativeBinding;\n    loadedFrom = path.dirname(candidate);\n    return binding;\n  }\n  const expected = platformPackage.packageName();\n  throw new Error(\n      'shotium: no engine for this platform.\\n' +\n      `  looked in:\\n    ${tried.join('\\n    ')}\\n` +\n      (expected ?\n           `  It ships in ${expected}, which npm installs as an optional ` +\n               'dependency of this package. If the install skipped optional ' +\n               'dependencies, it is not there.\\n' :\n           `  There is no build for ${process.platform}-${process.arch}.\\n`));\n}\n\n/**\n * The directory the addon came from, or null before the first load(). The\n * resource packs ship beside it, which is what this is for.\n */\nexport function directory(): string|null {\n  return loadedFrom;\n}\n","import * as binding from './binding.js';\nimport type {Engine as Handle} from './binding.js';\nimport {toRequest} from './request.js';\nimport type {WireRequest} from './request.js';\nimport type {PurgeOptions, ScreenshotOptions, StartOptions} from '../types.js';\n\nimport {resolveStartOptions} from './config.js';\n\n// One per process, ever. Not one at a time -- one.\n//\n// This is not a rule of this file, it is what Blink is: initialising it writes\n// process-wide statics it has no path to undo, so shot_engine_destroy() gives\n// back what it can and the process still cannot make another. The C API\n// returns SHOT_ERR_STATE for a second create whether or not the first is\n// still alive. See shot/shot_api.h.\n//\n// So `stop()` is final for the process, and this flag exists to say that in\n// words at the call site. Without it a caller who stops and starts again gets\n// SHOT_ERR_STATE out of the addon -- a true error, arriving one layer too deep\n// to explain that the answer is a second process rather than a retry.\nlet startedInThisProcess = false;\n\n/**\n * Blink, in this process, and the queue in front of it.\n *\n * There is one renderer and there is no way to have two. Blink is a\n * process-wide singleton: it is initialised once, there is no path to a second\n * one, and `worker_threads` do not change that because they share the process.\n * So captures are serialised however many callers there are, and a program\n * that wants four at once wants four processes.\n *\n * The queue is not about fairness. Each capture occupies a libuv thread pool\n * thread for as long as the render takes, and there are four of those by\n * default, shared with fs and dns -- so letting four screenshots go at once\n * would stall the host's file reads for a fifth of a second at a time while\n * gaining nothing, since the engine serialises them anyway.\n */\nexport class Engine {\n  private handle: Handle|null = null;\n  private stopped = false;\n  private tail: Promise<unknown> = Promise.resolve();\n\n  get running(): boolean {\n    return this.handle !== null;\n  }\n\n  /**\n   * Starts the engine. Safe to call twice; the second call is a no-op, so that\n   * library code can call it defensively.\n   *\n   * Not safe to call after `stop()`, and not because of anything here: Blink\n   * starts once per process and cannot be restarted. Another engine means\n   * another process.\n   */\n  start(options: StartOptions = {}): this {\n    if (this.handle) {\n      return this;\n    }\n    if (this.stopped) {\n      throw new Error(\n          'shotium: this engine was stopped, and Blink cannot be started ' +\n          'again in a process that has already run it. Start another ' +\n          'process, or keep the engine up between screenshots.');\n    }\n    if (startedInThisProcess) {\n      throw new Error(\n          'shotium: an engine has already run in this process. Blink is a ' +\n          'process-wide singleton -- there is one per process, ever -- so a ' +\n          'second Runtime cannot have one. Use the shared `runtime`, or run ' +\n          'another process.');\n    }\n    const native = binding.load();\n    const resolved = resolveStartOptions(options);\n\n    const engineOptions: Record<string, unknown> = {};\n    if (resolved.cacheDir !== null) {\n      engineOptions.cacheDir = resolved.cacheDir;\n    }\n    if (resolved.userAgent !== undefined) {\n      engineOptions.userAgent = resolved.userAgent;\n    }\n    // The packs sit beside the library, and the library cannot find itself on\n    // Linux -- the path the engine resolves for \"this module\" goes through\n    // /proc/self/exe, which names node. Saying it here is cheaper than\n    // teaching the engine a second way to look. See shot_api.h.\n    engineOptions.resourceDir = resolved.resourceDir ?? binding.directory();\n\n    this.handle = native.create(JSON.stringify(engineOptions));\n    startedInThisProcess = true;\n    return this;\n  }\n\n  /**\n   * Stops the engine, after whatever is queued.\n   *\n   * Final for this process: see the note above. A program that will want\n   * another screenshot later should leave the engine up and call `purge()`\n   * instead, which hands back the memory without giving up the engine.\n   */\n  async stop(): Promise<void> {\n    if (!this.handle) {\n      return;\n    }\n    this.stopped = true;\n    // After the queue, not before: destroy() waits for a capture in flight\n    // anyway, and doing it in order means a caller's last screenshot resolves\n    // rather than racing the shutdown.\n    const handle = this.handle;\n    this.handle = null;\n    await this.tail.catch(() => {});\n    binding.load().destroy(handle);\n  }\n\n  /**\n   * Hands back what the engine is holding but can rebuild.\n   * `releaseWorkingSet` additionally asks the OS for the pages, which the next\n   * screenshot pays back in soft faults -- worth it when there may not be a\n   * next one soon.\n   *\n   * The daemon does this for itself on a timer because it can watch its own\n   * request stream go quiet. Here the queue belongs to the caller, so the\n   * caller is the one who knows a batch has ended.\n   */\n  purge({releaseWorkingSet = false}: PurgeOptions = {}): void {\n    if (!this.handle) {\n      return;\n    }\n    binding.load().purge(this.handle, releaseWorkingSet);\n  }\n\n  /**\n   * Renders one screenshot. Resolves to the encoded image, or to `null` when\n   * `path` was given and the engine wrote the file itself.\n   */\n  // `async` and not a plain function returning capture()'s promise: toRequest()\n  // throws, and a caller who wrote `screenshot(bad).catch(...)` would get the\n  // throw past the catch and into the surrounding frame. The whole surface is\n  // promise-shaped, so a bad request is a rejection like everything else.\n  async screenshot(options: ScreenshotOptions): Promise<Buffer|null> {\n    // Before anything else, and before the queue: a malformed request should\n    // be a rejection now rather than one that waits its turn.\n    return this.capture(toRequest(options));\n  }\n\n  /**\n   * The same, for a request that is already in wire form.\n   *\n   * The daemon reads these off a socket, where they arrived having been\n   * validated by the client that sent them. Re-deriving one from\n   * ScreenshotOptions would mean the daemon validating a request it cannot see\n   * the original of, and rejecting fields a newer client legitimately sent.\n   */\n  async capture(request: WireRequest): Promise<Buffer|null> {\n    if (!this.handle) {\n      this.start();\n    }\n    const handle = this.handle;\n    const native = binding.load();\n\n    // Chain onto the tail so that captures run one at a time. The catch keeps\n    // one failure from poisoning everything queued behind it.\n    const result = this.tail.catch(() => {}).then(\n        () => native.capture(handle, JSON.stringify(request)));\n    this.tail = result.catch(() => {});\n    const image = await result;\n    return request.path ? null : image;\n  }\n}\n"],"mappings":"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"}