@shotkit/shotium 0.1.0 → 0.3.0

package/src/lib/platform.ts

@@ -66,10 +66,4 @@ function packageDir(): string|null {
   }
 }
 
-// What the engine executable is called, which is not what the platform calls
-// it: Windows wants the extension and nothing else does.
-function binaryName(): string {
-  return process.platform === 'win32' ? 'shotium.exe' : 'shotium';
-}
-
-export {PACKAGES, binaryName, packageDir, packageName};
+export {PACKAGES, packageDir, packageName};

package/src/lib/request.ts

@@ -1,14 +1,14 @@
-import type {Clip, PageGotoParams, ScreenshotOptions} from '../types.js';
+import type {
+  CacheMode,
+  Clip,
+  PageGotoParams,
+  ScreenshotOptions,
+} from '../types.js';
 
 const DEFAULT_TIMEOUT_MS = 30000;
-// How much longer than the page's own deadline a supervisor waits before
-// deciding the worker is not going to answer at all. The worker fails a slow
-// page by itself and replies; this margin covers process startup and the
-// encode, and firing it means something worse than a slow page.
-const SUPERVISOR_MARGIN_MS = 10000;
 
-// What actually goes down the pipe. It is ScreenshotOptions with the viewport
-// flattened and `retry` taken out -- see toRequest below for why each.
+// What actually goes down the pipe: ScreenshotOptions with the viewport
+// flattened -- see toRequest below for why.
 export interface WireRequest {
   file: string;
   type?: 'png'|'jpeg'|'webp';
@@ -21,6 +21,8 @@ export interface WireRequest {
   pageGotoParams?: PageGotoParams;
   clip?: Clip;
   allowFileAccess?: boolean;
+  cache?: CacheMode;
+  headers?: Record<string, string>;
   width?: number;
   height?: number;
 }
@@ -45,12 +47,14 @@ const WIRE_FIELDS = new Set([
   'clip',
   'viewport',
   'allowFileAccess',
+  'cache',
+  'headers',
 ]);
 
 // One ScreenshotOptions, checked and flattened into what goes on the wire.
 //
-// It lives here rather than in index.ts because the in-process pool and the
-// daemon both send it: a request that is valid through one entry point and
+// It lives here rather than in index.ts because the engine in this process and
+// the daemon both send it: a request that is valid through one entry point and
 // rejected through the other would be a difference nobody asked for.
 function toRequest(options: ScreenshotOptions): WireRequest {
   if (!options || typeof options !== 'object') {
@@ -65,11 +69,6 @@ function toRequest(options: ScreenshotOptions): WireRequest {
     if (value === undefined) {
       continue;
     }
-    // retry is the supervisor's, not the worker's: it decides how many times a
-    // request is re-sent, which is not something the worker could act on.
-    if (key === 'retry') {
-      continue;
-    }
     if (!WIRE_FIELDS.has(key)) {
       throw new TypeError(`shotium: unknown option "${key}"`);
     }
@@ -101,7 +100,6 @@ function timeoutFor(options: ScreenshotOptions): number {
 
 export {
   DEFAULT_TIMEOUT_MS,
-  SUPERVISOR_MARGIN_MS,
   WIRE_FIELDS,
   timeoutFor,
   toRequest,

package/src/types.ts

@@ -1,10 +1,8 @@
 // The vocabulary of the package: what a caller passes in and what comes back.
 //
 // It lives in one file rather than beside the code that reads each field
-// because these types are the published API. index.ts and native.ts both
-// re-export them, so a consumer sees one `ScreenshotOptions` whichever entry
-// point they came through -- and, more to the point, so there is one place
-// where adding an option means adding it.
+// because these types are the published API: index.ts re-exports them, so
+// there is one place where adding an option means adding it.
 
 /** A region of the document, in CSS pixels. */
 export interface Clip {
@@ -35,6 +33,69 @@ export interface Viewport {
   height?: number;
 }
 
+/**
+ * What a capture may do with the HTTP cache, spelled the way `fetch` spells
+ * it.
+ *
+ * - `default`: ordinary HTTP semantics. A fresh entry is used without asking,
+ *   a stale one is revalidated, and the response updates the cache.
+ * - `reload`: read nothing, write everything -- the browser's reload button.
+ *   The next capture is fast again.
+ * - `no-store`: neither read nor write. For a page that should not be left on
+ *   this machine's disk, which an authenticated one usually should not.
+ * - `only-if-cached`: the network may not be touched and a miss is an error.
+ *   Useful for a deterministic re-render of something already fetched.
+ */
+export type CacheMode = 'default'|'reload'|'no-store'|'only-if-cached';
+
+/** Where the milliseconds went. */
+export interface CaptureTiming {
+  /**
+   * Fetching the top-level document. For a cold `https:` URL this is DNS, TCP,
+   * TLS and a round trip, and it is routinely larger than everything below --
+   * which is the single most useful thing this object says.
+   */
+  fetch: number;
+  /** Parse, subresources, style, layout, prepaint, paint. */
+  render: number;
+  encode: number;
+  /** Wall clock for the whole capture, so the three above can be checked. */
+  total: number;
+}
+
+/** What one capture cost, and where its bytes came from. */
+export interface CaptureStats {
+  /** Every resource the document asked for, itself included. */
+  requests: number;
+  /**
+   * Answered from the HTTP cache -- the body came from disk.
+   *
+   * Not the same as "no network was touched". A stale entry that can be
+   * revalidated costs a conditional request and a 304, and counts here too;
+   * what the cache saved is the download rather than the round trip. That is
+   * why `timing.fetch` can be tens of milliseconds with this set.
+   */
+  fromCache: number;
+  failed: number;
+  /** Decoded body bytes, summed -- not the transfer size. */
+  bytes: number;
+  /** The document's own status. 0 for a `file:` URL. */
+  httpStatus: number;
+  /** After redirects, which is what relative URLs resolved against. */
+  finalUrl: string;
+  timing: CaptureTiming;
+}
+
+/** One screenshot, and what taking it cost. */
+export interface ScreenshotResult {
+  /**
+   * The encoded image, or `null` when `path` was given: the engine wrote the
+   * file itself and there is nothing left to hand back.
+   */
+  image: Buffer|null;
+  stats: CaptureStats;
+}
+
 export interface ScreenshotOptions {
   /** An http/https/file URL, or a local path. */
   file: string;
@@ -70,35 +131,92 @@ export interface ScreenshotOptions {
    * is rendered on.
    */
   allowFileAccess?: boolean;
-  /** How many times to re-send after a crash or a timeout. Default 0. */
-  retry?: number;
+  /**
+   * What this capture may do with the HTTP cache. Default `default`.
+   *
+   * It applies to the subresources as well as the document: a `reload` that
+   * refreshed the HTML and reused yesterday's stylesheet would be a confusing
+   * thing to have asked for.
+   */
+  cache?: CacheMode;
+  /**
+   * Extra request headers, sent with the document and with the subresources
+   * that are same-origin with it.
+   *
+   * Same-origin is the whole rule and it is not configurable. A caller passing
+   * `Authorization` or `Cookie` means it for the site being photographed; a
+   * page that pulls a script from a CDN must not have the credential
+   * forwarded there.
+   */
+  headers?: Record<string, string>;
 }
 
 export interface StartOptions {
   /**
-   * Path to `shotium.exe`. Default `$SHOTIUM_BINARY`, then the platform
-   * package for this machine, then `./bin/shotium.exe`.
+   * Root of the HTTP disk cache. `null` disables caching entirely.
+   *
+   * The default is a per-project directory under the system temporary
+   * directory -- see `cache.getDir()`. Caching is on by default because the
+   * alternative turned out to be worse: without it every capture of an
+   * `https:` URL pays for DNS, TLS and a round trip, which for a small page is
+   * most of the time the call takes and all of the time the caller did not
+   * expect to spend.
    */
-  binary?: string;
-  /** Worker processes. Default half the cores, at least one, at most four. */
-  workers?: number;
-  /** Root of the per-worker HTTP disk caches. `null` disables caching. */
   cacheDir?: string|null;
-  /** Extra flags passed to every worker. */
-  args?: string[];
+  /**
+   * Ceiling on the cache directory, in bytes. Default 256 MB.
+   *
+   * Zero is not "unlimited" -- it hands the decision to the backend, which
+   * sizes itself against the volume's free space. That was a reasonable
+   * default when every user of the cache had named a directory on purpose; for
+   * one that appears by default under `~/.shotium` because somebody imported a
+   * library, a number somebody chose is better than a number nobody did.
+   */
+  cacheMaxBytes?: number;
+  /** 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;
 }
 
-export interface WorkerEvent {
-  worker: number;
-  code?: number|null;
-  signal?: NodeJS.Signals|null;
+/** What `start()` reports about the engine it brought up. */
+export interface StartResult {
+  /**
+   * Whether this lifecycle is started.
+   *
+   * A process has at most one engine, so `false` here does not mean there is
+   * nothing running -- it means this `Runtime` is stood down. `cacheDir` below
+   * is still answered from the engine, because a stood-down engine keeps its
+   * cache directory and reporting `null` would say the cache had gone away
+   * when what went away was the willingness to render.
+   */
+  running: boolean;
+  /** The directory in use, or `null` when caching is off. */
+  cacheDir: string|null;
+  /**
+   * Whether that directory is actually being cached into.
+   *
+   * A directory that cannot be created or written to costs nothing visible:
+   * the engine renders exactly as well without a cache, only slower, and every
+   * capture pays for the network again for a reason nothing reports. `false`
+   * with a `cacheDir` set means the open failed; `false` with `cacheDir: null`
+   * means no cache was asked for.
+   *
+   * It is not about sharing. Several processes may use one directory and all
+   * of them cache -- the backend takes no cross-process lock -- so `true` in
+   * two processes at once is the ordinary answer.
+   */
+  cacheActive: boolean;
 }
 
 export interface DaemonOptions extends StartOptions {
   /**
    * Address the daemon by name instead of by configuration. Without it the
-   * endpoint is a hash of `binary`, `workers`, `cacheDir` and `args`, so a
-   * client never attaches to a pool that renders with something other than
+   * 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;
@@ -110,9 +228,8 @@ export interface DaemonOptions extends StartOptions {
    */
   idleTimeoutMs?: number;
   /**
-   * Render one throwaway document per worker at startup, so the first real
-   * request does not pay for whatever a worker initialises lazily. Default
-   * true.
+   * 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. */
@@ -129,11 +246,10 @@ export interface DaemonStatus {
   spawned?: boolean;
   pid: number;
   endpoint: string;
-  binary: string;
-  workers: number;
   cacheDir: string|null;
-  args: string[];
-  /** Every worker has rendered at least once. */
+  userAgent?: string;
+  resourceDir?: string;
+  /** The engine has rendered at least once. */
   warm: boolean;
   uptimeMs: number;
   connections: number;
@@ -143,27 +259,85 @@ export interface DaemonStatus {
   version: string;
 }
 
-export interface NativeStartOptions {
+/**
+ * Options for `releaseMemory()`.
+ *
+ * Named for what it does rather than for `purge`, which it was called until
+ * 0.3. With `cache.clear()` in the API the old name reads as though it clears
+ * the cache, and it does not: it hands back blink's heap, skia's caches and
+ * PartitionAlloc's free lists, all of which the engine rebuilds on demand.
+ * Nothing on disk is touched.
+ */
+export interface ReleaseMemoryOptions {
   /**
-   * Root of the HTTP disk cache. `null` disables caching entirely, which is
-   * the default here: an in-process engine is often a short-lived program, and
-   * a cache it never reads twice is a directory it leaves behind.
+   * 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.
    */
-  cacheDir?: string|null;
-  /** Overrides the built-in user agent string. */
-  userAgent?: string;
+  releaseWorkingSet?: boolean;
+}
+
+/** Which cache directory an operation is about. */
+export interface CacheTarget {
   /**
-   * Where `shotium_data.pak` and `shotium_strings.pak` are. Defaults to the
-   * directory the native engine was loaded from, which is where they ship.
+   * `current` (the default) is this project's directory, `all` is every
+   * directory shotium has created under the shared root -- `~/.shotium/cache`
+   * -- and a string is either an absolute path or one project hash as
+   * `getDir()` reports it.
+   *
+   * The absolute path is there because `start({cacheDir})` accepts any
+   * directory: without it, a caller who chose their own cache would have the
+   * one cache these methods could not see.
+   *
+   * `all` exists because the directories are per-project by default, so
+   * "clear shotium's caches" is otherwise something a caller cannot express
+   * without already knowing where the other projects were.
    */
-  resourceDir?: string;
+  target?: 'current'|'all'|(string&{});
 }
 
-export interface PurgeOptions {
+/** One resource the cache is holding. */
+export interface CacheEntry {
+  /** The resource, not the backend's key -- see `cache.getFiles()`. */
+  url: string;
+  /** Milliseconds since the Unix epoch. */
+  lastUsedMs: number;
+  bytes: number;
+  /** Which cache directory it was found in. */
+  dir: string;
+}
+
+export interface CacheClearOptions extends CacheTarget {
   /**
-   * 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.
+   * Glob patterns matched against entry URLs -- not against filenames, which
+   * are hashes and would match nothing anybody would think to write.
+   *
+   * Supports `*` (within a path segment), `**` (across segments), `?` and
+   * `{a,b}`. Matching happens here rather than in the engine: the entries come
+   * back first, the patterns are applied to their URLs, and the ones that
+   * matched are what gets removed.
    */
-  releaseWorkingSet?: boolean;
+  glob?: string[];
+  /**
+   * Remove entries not used for this many seconds. `0`, the default, means no
+   * age limit.
+   */
+  maxAge?: number;
+  /**
+   * Evict least-recently-used entries until the directory is at or below this
+   * many bytes. `0`, the default, means no size limit.
+   */
+  maxSize?: number;
+}
+
+export interface CacheClearResult {
+  /**
+   * How many entries went. `-1` when the whole directory was dropped in one
+   * operation, which the backend does without counting them.
+   */
+  removed: number;
+  bytesBefore: number;
+  bytesAfter: number;
+  /** Which directory this result is for. */
+  dir: string;
 }

package/dist/native.d.ts

@@ -1,66 +0,0 @@
-import { i as NativeStartOptions, o as PurgeOptions, s as ScreenshotOptions } from "./types-x9HtkzeE.js";
-//#region src/native.d.ts
-/**
- * The engine, in this process, and the queue in front of it.
- *
- * Same options and same output as `runtime`, and a different set of trades.
- * There is no worker process, so there is nothing to start, nothing to find on
- * disk and no pipe: a screenshot costs about a third less than through the
- * pool, and the whole thing is one process instead of five.
- *
- * What it gives up is what a separate process was providing for free. One
- * renderer, because blink is a process-wide singleton and `worker_threads`
- * share the process, so requests are serialised however many callers there
- * are. And no crash isolation: a renderer that dies takes the host program
- * with it, where the pool would have retried.
- *
- * 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.
- */
-declare class NativeRuntime {
-  private engine;
-  private tail;
-  get running(): boolean;
-  /**
-   * Starts the engine. Safe to call twice; the second call is a no-op.
-   *
-   * `cacheDir` is the HTTP disk cache and `null` disables it, which is the
-   * default here. `resourceDir` is where `shotium_data.pak` and
-   * `shotium_strings.pak` are, and defaults to the directory the addon was
-   * loaded from, which is where they ship.
-   */
-  start(options?: NativeStartOptions): this;
-  /** Stops the engine, after whatever is queued. */
-  stop(): Promise<void>;
-  /**
-   * 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 resident worker 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 }?: 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 in-process engine, started on first use. */
-declare const native: NativeRuntime;
-/** One screenshot through the shared in-process engine. */
-declare const screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
-declare const _default: {
-  NativeRuntime: typeof NativeRuntime;
-  native: NativeRuntime;
-  screenshot: (options: ScreenshotOptions) => Promise<Buffer | null>;
-};
-//#endregion
-export { NativeRuntime, type NativeStartOptions, type PurgeOptions, type ScreenshotOptions, _default as default, native, screenshot };
-//# sourceMappingURL=native.d.ts.map

package/dist/native.js

@@ -1,127 +0,0 @@
-import { n as packageDir, r as packageName } from "./platform-DU8DYqmA.js";
-import { r as toRequest } from "./request-qZXS3N9f.js";
-import { createRequire } from "node:module";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-//#region src/native.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 bindingDir = null;
-function load() {
-	if (binding) return binding;
-	const tried = candidates();
-	for (const candidate of tried) {
-		if (!fs.existsSync(candidate)) continue;
-		binding = require(candidate);
-		bindingDir = path.dirname(candidate);
-		return binding;
-	}
-	const expected = packageName();
-	throw new Error(`shotium: no native 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.
-` : `  There is no build for ${process.platform}-${process.arch}.\n`) + "  import(\"@shotkit/shotium\") uses worker processes instead and needs no addon.");
-}
-/**
-* The engine, in this process, and the queue in front of it.
-*
-* Same options and same output as `runtime`, and a different set of trades.
-* There is no worker process, so there is nothing to start, nothing to find on
-* disk and no pipe: a screenshot costs about a third less than through the
-* pool, and the whole thing is one process instead of five.
-*
-* What it gives up is what a separate process was providing for free. One
-* renderer, because blink is a process-wide singleton and `worker_threads`
-* share the process, so requests are serialised however many callers there
-* are. And no crash isolation: a renderer that dies takes the host program
-* with it, where the pool would have retried.
-*
-* 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 NativeRuntime = class {
-	engine = null;
-	tail = Promise.resolve();
-	get running() {
-		return this.engine !== null;
-	}
-	/**
-	* Starts the engine. Safe to call twice; the second call is a no-op.
-	*
-	* `cacheDir` is the HTTP disk cache and `null` disables it, which is the
-	* default here. `resourceDir` is where `shotium_data.pak` and
-	* `shotium_strings.pak` are, and defaults to the directory the addon was
-	* loaded from, which is where they ship.
-	*/
-	start(options = {}) {
-		if (this.engine) return this;
-		const native = load();
-		const engineOptions = {};
-		if (options.cacheDir !== null && options.cacheDir !== void 0) engineOptions.cacheDir = options.cacheDir;
-		if (options.userAgent !== void 0) engineOptions.userAgent = options.userAgent;
-		engineOptions.resourceDir = options.resourceDir || bindingDir;
-		this.engine = native.create(JSON.stringify(engineOptions));
-		return this;
-	}
-	/** Stops the engine, after whatever is queued. */
-	async stop() {
-		if (!this.engine) return;
-		const engine = this.engine;
-		this.engine = null;
-		await this.tail.catch(() => {});
-		load().destroy(engine);
-	}
-	/**
-	* 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 resident worker 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.engine) return;
-		load().purge(this.engine, 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) {
-		const request = toRequest(options);
-		if (!this.engine) this.start();
-		const engine = this.engine;
-		const native = load();
-		const result = this.tail.catch(() => {}).then(() => native.capture(engine, JSON.stringify(request)));
-		this.tail = result.catch(() => {});
-		const image = await result;
-		return request.path ? null : image;
-	}
-};
-/** The shared in-process engine, started on first use. */
-const native = new NativeRuntime();
-/** One screenshot through the shared in-process engine. */
-const screenshot = (options) => native.screenshot(options);
-var native_default = {
-	NativeRuntime,
-	native,
-	screenshot
-};
-
-//#endregion
-export { NativeRuntime, native_default as default, native, screenshot };
-//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"native.js","names":["platformPackage.packageDir","platformPackage.packageName"],"sources":["../src/native.ts"],"sourcesContent":["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 './lib/platform.js';\nimport {toRequest} from './lib/request.js';\nimport type {\n  NativeStartOptions,\n  PurgeOptions,\n  ScreenshotOptions,\n} from './types.js';\n\nexport type {\n  NativeStartOptions,\n  PurgeOptions,\n  ScreenshotOptions,\n} from './types.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// The engine handle the addon hands back. It is opaque on purpose: everything\n// that can be done with it is a call on the binding below.\ntype Engine = unknown;\n\n// What native/binding.cc exports. See shot/shot_api.h for the C ABI under it.\ninterface 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// shot in this process, instead of in workers beside it.\n//\n// The difference from `runtime` is not the API, which is the same\n// screenshot(options), and not the request format, which is byte for byte the\n// same JSON. It is where blink is:\n//\n//   runtime   N worker processes, one screenshot each at a time, a crash is a\n//             retry, memory is N copies of an engine\n//   native    one engine in this process, one screenshot at a time ever, a\n//             crash takes the program with it, memory is one copy\n//\n// One at a time is not a limitation of this file. Blink is a process-wide\n// singleton -- it is initialised once and there is no path to a second one --\n// so an in-process engine is one renderer no matter how it is driven, and\n// worker_threads do not change that because they share the process. A caller\n// who wants four screenshots at once wants four processes, which is what the\n// pool is for.\n//\n// What it buys is that there is no process to start, nothing to find on disk,\n// no pipe, and no supervisor: a program that takes a handful of screenshots\n// and exits pays for one engine and talks to it directly.\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 bindingDir: string|null = null;\n\nfunction 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    bindingDir = path.dirname(candidate);\n    return binding;\n  }\n  const expected = platformPackage.packageName();\n  throw new Error(\n      'shotium: no native 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.\\n' :\n           `  There is no build for ${process.platform}-${process.arch}.\\n`) +\n      '  import(\"@shotkit/shotium\") uses worker processes instead and needs ' +\n      'no addon.');\n}\n\n/**\n * The engine, in this process, and the queue in front of it.\n *\n * Same options and same output as `runtime`, and a different set of trades.\n * There is no worker process, so there is nothing to start, nothing to find on\n * disk and no pipe: a screenshot costs about a third less than through the\n * pool, and the whole thing is one process instead of five.\n *\n * What it gives up is what a separate process was providing for free. One\n * renderer, because blink is a process-wide singleton and `worker_threads`\n * share the process, so requests are serialised however many callers there\n * are. And no crash isolation: a renderer that dies takes the host program\n * with it, where the pool would have retried.\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 NativeRuntime {\n  private engine: Engine|null = null;\n  private tail: Promise<unknown> = Promise.resolve();\n\n  get running(): boolean {\n    return this.engine !== null;\n  }\n\n  /**\n   * Starts the engine. Safe to call twice; the second call is a no-op.\n   *\n   * `cacheDir` is the HTTP disk cache and `null` disables it, which is the\n   * default here. `resourceDir` is where `shotium_data.pak` and\n   * `shotium_strings.pak` are, and defaults to the directory the addon was\n   * loaded from, which is where they ship.\n   */\n  start(options: NativeStartOptions = {}): this {\n    if (this.engine) {\n      return this;\n    }\n    const native = load();\n\n    const engineOptions: Record<string, unknown> = {};\n    if (options.cacheDir !== null && options.cacheDir !== undefined) {\n      engineOptions.cacheDir = options.cacheDir;\n    }\n    if (options.userAgent !== undefined) {\n      engineOptions.userAgent = options.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 = options.resourceDir || bindingDir;\n\n    this.engine = native.create(JSON.stringify(engineOptions));\n    return this;\n  }\n\n  /** Stops the engine, after whatever is queued. */\n  async stop(): Promise<void> {\n    if (!this.engine) {\n      return;\n    }\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 engine = this.engine;\n    this.engine = null;\n    await this.tail.catch(() => {});\n    load().destroy(engine);\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 resident worker does this for itself on a timer because it can watch\n   * its own request stream go quiet. Here the queue belongs to the caller, so\n   * the caller is the one who knows a batch has ended.\n   */\n  purge({releaseWorkingSet = false}: PurgeOptions = {}): void {\n    if (!this.engine) {\n      return;\n    }\n    load().purge(this.engine, 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 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    const request = toRequest(options);\n    if (!this.engine) {\n      this.start();\n    }\n    const engine = this.engine;\n    const native = 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(engine, JSON.stringify(request)));\n    this.tail = result.catch(() => {});\n    const image = await result;\n    return request.path ? null : image;\n  }\n}\n\n/** The shared in-process engine, started on first use. */\nconst native = new NativeRuntime();\n\n/** One screenshot through the shared in-process engine. */\nconst screenshot = (options: ScreenshotOptions): Promise<Buffer|null> =>\n    native.screenshot(options);\n\nexport {native, screenshot};\n\nexport default {NativeRuntime, native, screenshot};\n"],"mappings":";;;;;;;;AAoBA,MAAM,UAAU,cAAc,YAAY,GAAG;AAG7C,MAAM,OAAO,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AA4CxD,SAAS,aAAuB;CAC9B,MAAM,QAAkB,CAAC;CACzB,MAAM,MAAMA,WAA2B;CACvC,IAAI,KACF,MAAM,KAAK,KAAK,KAAK,KAAK,cAAc,CAAC;CAE3C,MAAM,KACF,KAAK,KAAK,MAAM,MAAM,UAAU,SAAS,WAAW,cAAc,CAAC;CACvE,OAAO;AACT;AAEA,IAAI,UAA8B;AAClC,IAAI,aAA0B;AAE9B,SAAS,OAAsB;CAC7B,IAAI,SACF,OAAO;CAET,MAAM,QAAQ,WAAW;CACzB,KAAK,MAAM,aAAa,OAAO;EAC7B,IAAI,CAAC,GAAG,WAAW,SAAS,GAC1B;EAMF,UAAU,QAAQ,SAAS;EAC3B,aAAa,KAAK,QAAQ,SAAS;EACnC,OAAO;CACT;CACA,MAAM,WAAWC,YAA4B;CAC7C,MAAM,IAAI,MACN;oBACqB,MAAM,KAAK,QAAQ,EAAE,OACzC,WACI,iBAAiB,SAAS;IAE1B,2BAA2B,QAAQ,SAAS,GAAG,QAAQ,KAAK,QACjE,kFACW;AACjB;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAa,gBAAb,MAA2B;CACzB,AAAQ,SAAsB;CAC9B,AAAQ,OAAyB,QAAQ,QAAQ;CAEjD,IAAI,UAAmB;EACrB,OAAO,KAAK,WAAW;CACzB;;;;;;;;;CAUA,MAAM,UAA8B,CAAC,GAAS;EAC5C,IAAI,KAAK,QACP,OAAO;EAET,MAAM,SAAS,KAAK;EAEpB,MAAM,gBAAyC,CAAC;EAChD,IAAI,QAAQ,aAAa,QAAQ,QAAQ,aAAa,QACpD,cAAc,WAAW,QAAQ;EAEnC,IAAI,QAAQ,cAAc,QACxB,cAAc,YAAY,QAAQ;EAMpC,cAAc,cAAc,QAAQ,eAAe;EAEnD,KAAK,SAAS,OAAO,OAAO,KAAK,UAAU,aAAa,CAAC;EACzD,OAAO;CACT;;CAGA,MAAM,OAAsB;EAC1B,IAAI,CAAC,KAAK,QACR;EAKF,MAAM,SAAS,KAAK;EACpB,KAAK,SAAS;EACd,MAAM,KAAK,KAAK,YAAY,CAAC,CAAC;EAC9B,KAAK,CAAC,CAAC,QAAQ,MAAM;CACvB;;;;;;;;;;;CAYA,MAAM,EAAC,oBAAoB,UAAuB,CAAC,GAAS;EAC1D,IAAI,CAAC,KAAK,QACR;EAEF,KAAK,CAAC,CAAC,MAAM,KAAK,QAAQ,iBAAiB;CAC7C;;;;;CAMA,MAAM,WAAW,SAAkD;EAGjE,MAAM,UAAU,UAAU,OAAO;EACjC,IAAI,CAAC,KAAK,QACR,KAAK,MAAM;EAEb,MAAM,SAAS,KAAK;EACpB,MAAM,SAAS,KAAK;EAIpB,MAAM,SAAS,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,WAC/B,OAAO,QAAQ,QAAQ,KAAK,UAAU,OAAO,CAAC,CAAC;EACzD,KAAK,OAAO,OAAO,YAAY,CAAC,CAAC;EACjC,MAAM,QAAQ,MAAM;EACpB,OAAO,QAAQ,OAAO,OAAO;CAC/B;AACF;;AAGA,MAAM,SAAS,IAAI,cAAc;;AAGjC,MAAM,cAAc,YAChB,OAAO,WAAW,OAAO;AAI7B,qBAAe;CAAC;CAAe;CAAQ;AAAU"}

package/dist/platform-DU8DYqmA.js

@@ -1,32 +0,0 @@
-import { createRequire } from "node:module";
-import path from "node:path";
-
-//#region src/lib/platform.ts
-const require = 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.resolve(`${name}/package.json`));
-	} catch {
-		return null;
-	}
-}
-function binaryName() {
-	return process.platform === "win32" ? "shotium.exe" : "shotium";
-}
-
-//#endregion
-export { packageDir as n, packageName as r, binaryName as t };
-//# sourceMappingURL=platform-DU8DYqmA.js.map

package/dist/platform-DU8DYqmA.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"platform-DU8DYqmA.js","names":[],"sources":["../src/lib/platform.ts"],"sourcesContent":["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\n// What the engine executable is called, which is not what the platform calls\n// it: Windows wants the extension and nothing else does.\nfunction binaryName(): string {\n  return process.platform === 'win32' ? 'shotium.exe' : 'shotium';\n}\n\nexport {PACKAGES, binaryName, packageDir, packageName};\n"],"mappings":";;;;AAKA,MAAM,UAAU,cAAc,YAAY,GAAG;AA8B7C,MAAM,WAA6C;CACjD,aAAa;CACb,eAAe;CACf,cAAc;CACd,gBAAgB;CAChB,aAAa;CACb,eAAe;AACjB;AAEA,SAAS,YACL,WAAmB,QAAQ,UAC3B,OAAe,QAAQ,MAAmB;CAC5C,OAAO,SAAS,GAAG,SAAS,GAAG,WAAW;AAC5C;AAQA,SAAS,aAA0B;CACjC,MAAM,OAAO,YAAY;CACzB,IAAI,CAAC,MACH,OAAO;CAET,IAAI;EACF,OAAO,KAAK,QAAQ,QAAQ,QAAQ,GAAG,KAAK,cAAc,CAAC;CAC7D,QAAQ;EACN,OAAO;CACT;AACF;AAIA,SAAS,aAAqB;CAC5B,OAAO,QAAQ,aAAa,UAAU,gBAAgB;AACxD"}