@shotkit/shotium 0.0.1 → 0.2.0

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

@@ -0,0 +1,267 @@
+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

@@ -0,0 +1 @@
+{"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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"}

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { EventEmitter } from "node:events";
+import net from "node:net";
+//#region src/types.d.ts
+/** A region of the document, in CSS pixels. */
+interface Clip {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface PageGotoParams {
+  /** Milliseconds before the load is abandoned. Default 30000. */
+  timeout?: number;
+  /**
+   * `load` waits for parsing to finish, the load event to fire and every
+   * request to complete. `networkidle` additionally waits for a 500ms window
+   * with nothing in flight, which matters for documents that keep fetching
+   * after the load event -- CSS that pulls in more CSS, or a font a late style
+   * change brought in.
+   */
+  waitUntil?: 'load' | 'networkidle';
+}
+/** The viewport the document is laid out in. */
+interface Viewport {
+  /** CSS pixels. Default 1280. */
+  width?: number;
+  /** CSS pixels. Default 720. */
+  height?: number;
+}
+interface ScreenshotOptions {
+  /** An http/https/file URL, or a local path. */
+  file: string;
+  /** Default `png`. */
+  type?: 'png' | 'jpeg' | 'webp';
+  /** Capture the whole document rather than the viewport. */
+  fullPage?: boolean;
+  /**
+   * Capture the box of the first element matching this CSS selector. Resolved
+   * inside the renderer with Document::querySelector -- there is no JavaScript
+   * engine, so nothing is injected into the page.
+   */
+  selector?: string;
+  /** 1-100, `jpeg` and `webp` only. Default 90. */
+  quality?: number;
+  /** Device scale factor, 0.01-8. Default 1. */
+  scale?: number;
+  /**
+   * Keep the alpha channel instead of painting the page's white backdrop.
+   * Rejected for `jpeg`, which has no alpha channel.
+   */
+  omitBackground?: boolean;
+  /** Write the image here instead of returning it, saving a round trip. */
+  path?: string;
+  pageGotoParams?: PageGotoParams;
+  /** A region of the document, in CSS pixels. */
+  clip?: Clip;
+  /** The viewport the document is laid out in. */
+  viewport?: Viewport;
+  /**
+   * Let the document read `file:` subresources. Off by default: a library does
+   * not get to decide for its caller that a document may read the filesystem it
+   * is rendered on.
+   */
+  allowFileAccess?: boolean;
+}
+interface StartOptions {
+  /**
+   * Root of the HTTP disk cache. `null` disables caching entirely, which is
+   * the default: a program holding the engine is often short-lived, and a
+   * cache it never reads twice is a directory it leaves behind.
+   */
+  cacheDir?: string | null;
+  /** Overrides the built-in user agent string. */
+  userAgent?: string;
+  /**
+   * Where `shotium_data.pak` and `shotium_strings.pak` are. Defaults to the
+   * directory the engine was loaded from, which is where they ship.
+   */
+  resourceDir?: string;
+}
+interface DaemonOptions extends StartOptions {
+  /**
+   * Address the daemon by name instead of by configuration. Without it the
+   * endpoint is a hash of `cacheDir`, `userAgent` and `resourceDir`, so a
+   * client never attaches to a daemon that renders with something other than
+   * what it asked for.
+   */
+  name?: string;
+  /** The pipe or socket to use, overriding both the name and the hash. */
+  endpoint?: string;
+  /**
+   * Exit after this long with no connections and nothing rendering. Default
+   * 300000; `0` never exits.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * Render one throwaway document at startup, so the first real request does
+   * not pay for whatever the engine initialises lazily. Default true.
+   */
+  prewarm?: boolean;
+  /** Fail instead of starting a daemon when none is listening. */
+  spawn?: boolean;
+  /** Where a spawned daemon's diagnostics go. Default `$SHOTIUM_DAEMON_LOG`. */
+  logFile?: string;
+  /** How long to wait for a daemon this process started to bind. */
+  startTimeoutMs?: number;
+}
+interface DaemonStatus {
+  ok?: boolean;
+  running?: boolean;
+  spawned?: boolean;
+  pid: number;
+  endpoint: string;
+  cacheDir: string | null;
+  userAgent?: string;
+  resourceDir?: string;
+  /** The engine has rendered at least once. */
+  warm: boolean;
+  uptimeMs: number;
+  connections: number;
+  inFlight: number;
+  served: number;
+  idleTimeoutMs: number;
+  version: string;
+}
+interface PurgeOptions {
+  /**
+   * Also ask the OS to take the engine's pages back. The next screenshot pays
+   * them back in soft page faults -- a few milliseconds -- so this is for when
+   * there may not be a next one soon.
+   */
+  releaseWorkingSet?: boolean;
+}
+//#endregion
+//#region src/lib/client.d.ts
+interface ClientReply {
+  id: number;
+  ok?: boolean;
+  error?: string;
+  path?: string;
+}
+interface ClientResult {
+  header: ClientReply;
+  image: Buffer | null;
+}
+declare class DaemonClient extends EventEmitter {
+  private readonly socket;
+  private readonly endpointPath;
+  private readonly pending;
+  private nextId;
+  private header;
+  private reader;
+  constructor(socket: net.Socket, endpoint: string);
+  get endpoint(): string;
+  get closed(): boolean;
+  private onData;
+  private settle;
+  private failAll;
+  send(message: Record<string, unknown>): Promise<ClientResult>;
+  /** Resolves to the image, or to null when `path` was given. */
+  screenshot(options: ScreenshotOptions): Promise<Buffer | null>;
+  status(): Promise<DaemonStatus>;
+  shutdown(): Promise<{
+    ok: boolean;
+  }>;
+  close(): void;
+}
+//#endregion
+//#region src/index.d.ts
+/** The five things a caller does with the resident engine. */
+interface Daemon {
+  /** Connects, starting a daemon if none is listening. */
+  connect(options?: DaemonOptions): Promise<DaemonClient>;
+  /** One screenshot through the daemon, connection and all. */
+  screenshot(options: ScreenshotOptions & {
+    daemon?: DaemonOptions;
+  }): Promise<Buffer | null>;
+  /** Starts one if it is not up, and reports what is there either way. */
+  start(options?: DaemonOptions): Promise<DaemonStatus & {
+    spawned: boolean;
+  }>;
+  status(options?: DaemonOptions): Promise<Partial<DaemonStatus> & {
+    running: boolean;
+    endpoint: string;
+  }>;
+  stop(options?: DaemonOptions): Promise<{
+    stopped: boolean;
+    endpoint: string;
+  }>;
+}
+/**
+ * The engine, and its lifecycle, in this process.
+ *
+ *     import shotium from '@shotkit/shotium';
+ *
+ *     shotium.runtime.start();
+ *     const png = await shotium.screenshot({file: 'https://example.com'});
+ *     await shotium.runtime.stop();
+ *
+ * `start` and `stop` are explicit because starting Blink is the expensive part
+ * -- tens of milliseconds and a working set that stays resident -- and only
+ * the caller knows whether the next screenshot is coming in a moment or never.
+ * Neither call is required: a screenshot starts the engine if it is not up.
+ * What they buy is control over when that cost is paid, and the certainty that
+ * it has been given back.
+ *
+ * `runtime` below is the singleton because there is nothing else it could be:
+ * Blink starts once per process and cannot be restarted, so a second Runtime
+ * in the same process has no engine to have. Construct one directly only to
+ * own the lifecycle yourself instead of using `runtime`. Parallelism is more
+ * processes, not more Runtimes.
+ *
+ * `daemon` is the same engine in a process of its own, behind a socket, for
+ * callers whose own process does not live long enough to be worth starting
+ * one.
+ */
+declare class Runtime {
+  private engine;
+  get running(): boolean;
+  /**
+   * Starts the engine. Safe to call twice; the second call is a no-op, so that
+   * library code can call it defensively. Not safe after `stop()` -- see there.
+   *
+   * Every option has a default. `cacheDir` is the HTTP disk cache and `null`
+   * disables it; `resourceDir` is where `shotium_data.pak` and
+   * `shotium_strings.pak` are, and defaults to the directory the engine was
+   * loaded from, which is where they ship.
+   */
+  start(options?: StartOptions): this;
+  /**
+   * Stops the engine, after whatever is queued.
+   *
+   * Final for this process. Blink writes process-wide state that it has no
+   * path to undo, so starting again -- here or on another Runtime -- throws
+   * rather than quietly handing back something that cannot render. A program
+   * that wants another screenshot later should stay started and `purge()`.
+   */
+  stop(): Promise<void>;
+  /**
+   * Hands back what the engine is holding but can rebuild. Worth calling when
+   * a batch has ended and the next one may be a while away.
+   */
+  purge(options?: PurgeOptions): void;
+  /**
+   * Renders one screenshot. Resolves to the encoded image, or to `null` when
+   * `path` was given and the engine wrote the file itself.
+   */
+  screenshot(options: ScreenshotOptions): Promise<Buffer | null>;
+}
+/** The shared engine: one per process, started on first use. */
+declare const runtime: Runtime;
+/** One screenshot through the shared engine, starting it if it is not up. */
+declare const screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
+/**
+ * The resident engine: a process that outlives the one that started it,
+ * reachable over a named pipe on Windows and a unix socket elsewhere. For
+ * callers that are short-lived themselves. See lib/daemon.ts.
+ */
+declare const daemon: Daemon;
+declare const _default: {
+  Runtime: typeof Runtime;
+  runtime: Runtime;
+  screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
+  daemon: Daemon;
+};
+//#endregion
+export { type Clip, Daemon, type DaemonClient, type DaemonOptions, type DaemonStatus, type PageGotoParams, type PurgeOptions, Runtime, type ScreenshotOptions, type StartOptions, type Viewport, daemon, _default as default, runtime, screenshot };
+//# sourceMappingURL=index.d.ts.map