@shotkit/shotium 0.0.1 → 0.2.0

package/native/binding.gyp

@@ -0,0 +1,54 @@
+{
+  # How the addon is built. It is not built by `npm install`: shot itself is a
+  # Chromium fork that takes hours and a checkout to compile, so the library
+  # this links against is a release artifact, and the addon is built against it
+  # once per platform and shipped prebuilt.
+  #
+  #   SHOT_INCLUDE_DIR=/path/to/shot   (the directory holding shot_api.h)
+  #   SHOT_LIB_DIR=/path/to/out/Shot   (the directory holding the library)
+  #   npx node-gyp rebuild
+  "variables": {
+    # Not the engine's source directory: a directory holding a copy of
+    # shot_api.h and nothing else. An include directory pointed at shot/ makes
+    # libc++'s `#include <version>` resolve to shot/VERSION on any
+    # case-insensitive filesystem, which is macOS out of the box. See
+    # stage_header.js, which does the copying and explains the rest.
+    #
+    # SHOT_INCLUDE_DIR still says where shot_api.h is; stage_header.js reads it.
+    "shot_include_dir%": "<!(node stage_header.js)",
+    "shot_lib_dir%": "<!(node -p \"process.env.SHOT_LIB_DIR || require('path').resolve('../../out/Shot')\")"
+  },
+  "targets": [
+    {
+      "target_name": "shotium",
+      "sources": ["binding.cc"],
+      "include_dirs": ["<(shot_include_dir)"],
+      # Node-API 8 is Node 12.22 / 14.17 and up. Declaring it pins the surface
+      # this addon may use, so a build cannot quietly start depending on a
+      # newer node than the one it claims to support.
+      "defines": ["NAPI_VERSION=8"],
+      "cflags!": ["-fno-exceptions"],
+      "cflags_cc!": ["-fno-exceptions"],
+      "conditions": [
+        ["OS=='win'", {
+          # The import library GN writes beside the DLL. The DLL itself is
+          # found at run time in the directory the .node was loaded from.
+          "libraries": ["<(shot_lib_dir)/shotium.dll.lib"]
+        }],
+        ["OS=='linux'", {
+          "libraries": [
+            "-L<(shot_lib_dir)",
+            "-lshotium",
+            # $ORIGIN, escaped past make: the library ships beside the .node,
+            # not in a system directory, and nothing should be searching the
+            # host's library path for something named this generally.
+            "-Wl,-rpath,'$$ORIGIN'"
+          ]
+        }],
+        ["OS=='mac'", {
+          "libraries": ["-L<(shot_lib_dir)", "-lshotium", "-Wl,-rpath,@loader_path"]
+        }]
+      ]
+    }
+  ]
+}

package/native/stage_header.js

@@ -0,0 +1,53 @@
+// Puts shot_api.h somewhere it is the only thing there, and prints where.
+//
+// binding.gyp calls this at generate time and uses the result as the addon's
+// one include directory. The obvious thing -- pointing the include directory
+// straight at shot/ -- does not survive a case-insensitive filesystem:
+//
+//   src/shot/version:1:10: error: expected ';' after top level declarator
+//       1 | MAJOR=153
+//
+// That is libc++'s <string> including <version>, the compiler searching the
+// include directories before the system ones, and macOS answering `version`
+// with `shot/VERSION`, which is this tree's build number file. The same trap is
+// set on Windows -- NTFS is case-insensitive too -- and springs only because
+// MSVC's <string> happens not to reach for <version>.
+//
+// Renaming the file is not available: shot/VERSION is what this fork calls
+// chrome/VERSION, and //base, //build and a dozen .gni files name it. Nor is
+// -iquote, which would say exactly the right thing and has a different
+// spelling in each of the three generators node-gyp drives. Copying the one
+// header the addon needs into a directory of its own is what is left, and it
+// has the advantage that nothing about it can be undone by an STL that starts
+// including one more thing.
+//
+// SHOT_INCLUDE_DIR still names where shot_api.h is *found*; it just is not
+// handed to the compiler any more.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+// ESM has no __dirname. This is the same thing, from the module's own URL.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const HEADER = 'shot_api.h';
+
+const source = process.env.SHOT_INCLUDE_DIR ||
+    path.resolve(HERE, '..', '..', 'shot');
+const staged = path.resolve(HERE, 'build', 'include');
+
+const from = path.join(source, HEADER);
+if (!fs.existsSync(from)) {
+  process.stderr.write(
+      `stage_header.js: no ${HEADER} in ${source}\n` +
+      '  Set SHOT_INCLUDE_DIR to the directory holding it.\n');
+  process.exit(1);
+}
+
+fs.mkdirSync(staged, {recursive: true});
+fs.copyFileSync(from, path.join(staged, HEADER));
+
+// gyp takes this whole line as the variable's value, so it is the only thing
+// written to stdout.
+process.stdout.write(staged);

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@shotkit/shotium",
-  "version": "0.0.1",
-  "description": "Placeholder release to reserve the package name for Trusted Publishing.",
-  "license": "MIT"
+  "version": "0.2.0",
+  "description": "Static screenshots from a stripped Chromium: DOM, CSS, layout, paint, no JavaScript engine.",
+  "keywords": [
+    "screenshot",
+    "chromium",
+    "blink",
+    "html-to-image",
+    "png",
+    "render"
+  ],
+  "homepage": "https://github.com/sj817/shotium#readme",
+  "bugs": "https://github.com/sj817/shotium/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sj817/shotium.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "native/binding.cc",
+    "native/binding.gyp",
+    "native/stage_header.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@shotkit/shotium-darwin-arm64": "0.2.0",
+    "@shotkit/shotium-darwin-x64": "0.2.0",
+    "@shotkit/shotium-linux-arm64": "0.2.0",
+    "@shotkit/shotium-linux-x64": "0.2.0",
+    "@shotkit/shotium-win32-arm64": "0.2.0",
+    "@shotkit/shotium-win32-x64": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check:types": "tsc --noEmit",
+    "prepack": "tsdown"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "tsdown": "0.22.14",
+    "typescript": "5.9.3"
+  },
+  "license": "BSD-3-Clause"
 }

package/src/daemon_main.ts

@@ -0,0 +1,76 @@
+// The entry point of a detached daemon process.
+//
+// The configuration arrives as one base64 argument rather than as flags,
+// because it contains paths that a Windows command line would otherwise quote
+// badly, and because the client and the daemon have to agree on it exactly:
+// the endpoint is a hash of these fields, so a value mangled in transit would
+// produce a daemon listening where nobody looks. See endpoint.ts.
+//
+// It is a build entry of its own, and not a chunk, because lib/client.ts
+// spawns it by path -- `node dist/daemon_main.js <base64 json>` -- and a name
+// the bundler chose would be a name that changes.
+
+import {Daemon} from './lib/daemon.js';
+import type {DaemonOptions} from './types.js';
+
+async function main(): Promise<void> {
+  const encoded = process.argv[2];
+  if (!encoded) {
+    process.stderr.write('shotium: daemon_main expects a base64 config\n');
+    process.exit(2);
+  }
+  const options = JSON.parse(Buffer.from(encoded, 'base64').toString('utf8')) as
+      DaemonOptions;
+  const daemon = new Daemon(options);
+
+  daemon.on('stderr', ({worker, line}: {worker: number, line: string}) => {
+    process.stderr.write(`shotium worker ${worker}: ${line}\n`);
+  });
+  for (const event of ['crash', 'timeout', 'worker-restart', 'worker-error',
+                       'idle-exit']) {
+    daemon.on(event, (payload: {error?: unknown}) => {
+      // An Error does not survive JSON.stringify -- it comes out as {} -- and
+      // its message is the whole point of logging a worker that would not
+      // start.
+      const detail = payload && payload.error ?
+          {
+            ...payload,
+            error: String(
+                (payload.error as Error).message ?? payload.error),
+          } :
+          payload;
+      process.stderr.write(
+          `shotium daemon ${event}: ${JSON.stringify(detail)}\n`);
+    });
+  }
+  // An 'error' with nobody listening is thrown by EventEmitter itself, which
+  // would turn a socket that failed after binding -- something the daemon can
+  // survive -- into a dead pool.
+  daemon.on('error', (error: Error) => {
+    process.stderr.write(
+        `shotium daemon error: ${(error && error.message) || error}\n`);
+  });
+
+  try {
+    await daemon.listen();
+  } catch (error) {
+    // Losing the race to bind is the ordinary outcome when two clients start a
+    // daemon at the same moment: the other one is up, this one is not needed,
+    // and the client that spawned it will connect to the winner. Anything else
+    // is a real failure and says so.
+    if ((error as NodeJS.ErrnoException | null)?.code === 'EADDRINUSE') {
+      process.exit(0);
+    }
+    process.stderr.write(`shotium: daemon failed to start: ${error}\n`);
+    process.exit(1);
+  }
+
+  const shutdown = () => {
+    daemon.close().then(() => process.exit(0), () => process.exit(1));
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  daemon.on('close', () => process.exit(0));
+}
+
+void main();

package/src/index.ts

@@ -0,0 +1,139 @@
+import * as client from './lib/client.js';
+import type {DaemonClient} from './lib/client.js';
+import {Engine} from './lib/engine.js';
+import type {
+  DaemonOptions,
+  DaemonStatus,
+  PurgeOptions,
+  ScreenshotOptions,
+  StartOptions,
+} from './types.js';
+
+export type {
+  Clip,
+  DaemonOptions,
+  DaemonStatus,
+  PageGotoParams,
+  PurgeOptions,
+  ScreenshotOptions,
+  StartOptions,
+  Viewport,
+} from './types.js';
+export type {DaemonClient} from './lib/client.js';
+
+/** The five things a caller does with the resident engine. */
+export 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.
+ */
+export class Runtime {
+  private engine = new Engine();
+
+  get running(): boolean {
+    return this.engine.running;
+  }
+
+  /**
+   * 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 {
+    this.engine.start(options);
+    return 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> {
+    return this.engine.stop();
+  }
+
+  /**
+   * 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 {
+    this.engine.purge(options);
+  }
+
+  /**
+   * 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> {
+    return this.engine.screenshot(options);
+  }
+}
+
+/** The shared engine: one per process, started on first use. */
+const runtime = new Runtime();
+
+/** One screenshot through the shared engine, starting it if it is not up. */
+const screenshot = (options: ScreenshotOptions): Promise<Buffer|null> =>
+    runtime.screenshot(options);
+
+/**
+ * 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.
+ */
+const daemon: Daemon = {
+  connect: client.connect,
+  screenshot: client.screenshot,
+  start: client.start,
+  status: client.status,
+  stop: client.stop,
+};
+
+export {runtime, screenshot, daemon};
+
+// A default as well as the names, because `import shotium from` is what a
+// caller coming from `require` writes first, and the two have to be the same
+// object rather than two views that drift.
+export default {Runtime, runtime, screenshot, daemon};

package/src/lib/binding.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import * as platformPackage from './platform.js';
+
+// A .node addon is a CommonJS artefact: there is no ESM loader for one.
+const require = createRequire(import.meta.url);
+
+// ESM has no __dirname. This is the same thing, from the module's own URL.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The engine handle the addon hands back. Opaque on purpose: everything that
+ * can be done with it is a call on the binding below.
+ */
+export type Engine = unknown;
+
+/** What native/binding.cc exports. See shot/shot_api.h for the C ABI. */
+export interface NativeBinding {
+  create(optionsJson: string): Engine;
+  destroy(engine: Engine): void;
+  purge(engine: Engine, releaseWorkingSet: boolean): void;
+  capture(engine: Engine, requestJson: string): Promise<Buffer>;
+}
+
+// Where the addon and the library beside it live.
+//
+// The platform package is what ships -- the .node sits next to the shared
+// library it is linked against, which is the whole reason the two travel in
+// one package rather than two. native/build/Release is where node-gyp puts a
+// local build; it exists in a checkout and not in an install, so the two never
+// compete in practice. Both paths are relative to this file's build output,
+// which is one directory below the package root.
+function candidates(): string[] {
+  const found: string[] = [];
+  const dir = platformPackage.packageDir();
+  if (dir) {
+    found.push(path.join(dir, 'shotium.node'));
+  }
+  found.push(
+      path.join(HERE, '..', 'native', 'build', 'Release', 'shotium.node'));
+  return found;
+}
+
+let binding: NativeBinding|null = null;
+let loadedFrom: string|null = 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.
+ */
+export function load(): NativeBinding {
+  if (binding) {
+    return binding;
+  }
+  const tried = candidates();
+  for (const candidate of tried) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    // Not wrapped in a try: a .node that is there and will not load is a
+    // broken installation, and the loader's own message -- a missing
+    // dependency, an architecture mismatch -- says more than anything that
+    // could be substituted for it.
+    binding = require(candidate) as NativeBinding;
+    loadedFrom = path.dirname(candidate);
+    return binding;
+  }
+  const expected = platformPackage.packageName();
+  throw new Error(
+      'shotium: no engine for this platform.\n' +
+      `  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.\n' :
+           `  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.
+ */
+export function directory(): string|null {
+  return loadedFrom;
+}