@shotkit/shotium 0.0.1 → 0.1.0

package/native/binding.cc

@@ -0,0 +1,283 @@
+// Copyright 2026 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// shotium's node addon: shot in this process, over shot_api.h.
+//
+// It is deliberately thin. Everything about what a screenshot means -- which
+// fields exist, what they default to, what an unknown one is -- lives in
+// shotium/src/lib/request.ts and shot/shot_request.cc, and this file carries
+// JSON between them without reading it. Anything it understood would be a
+// third opinion about the request format, and the third opinion is always the
+// one that drifts.
+//
+// Node-API rather than V8: the ABI is stable across node versions, so one
+// prebuilt .node per platform is enough and the addon does not have to be
+// rebuilt every time node's internals move.
+
+#include <node_api.h>
+
+#include <cstring>
+#include <string>
+#include <utility>
+
+#include "shot_api.h"
+
+namespace {
+
+// A shot_engine, as node sees it.
+//
+// Wrapped rather than handed over as a bare pointer so that a script dropping
+// the handle on the floor still shuts the engine down: the finalizer runs when
+// the object is collected. `engine` is cleared by an explicit destroy() so the
+// finalizer does not do it twice.
+struct EngineHandle {
+  shot_engine* engine = nullptr;
+};
+
+void FinalizeEngine(napi_env env, void* data, void* hint) {
+  auto* handle = static_cast<EngineHandle*>(data);
+  if (handle->engine) {
+    shot_engine_destroy(handle->engine);
+  }
+  delete handle;
+}
+
+// One capture in flight: a promise, and the strings on both sides of it.
+//
+// The request is copied rather than referenced because Execute runs on a
+// libuv thread where no JS value may be touched, and the JS string it came
+// from can be collected before then.
+struct CaptureTask {
+  napi_deferred deferred = nullptr;
+  napi_async_work work = nullptr;
+  shot_engine* engine = nullptr;
+  std::string request;
+  shot_status status = SHOT_ERR_CAPTURE;
+  shot_buffer* image = nullptr;
+  shot_buffer* error = nullptr;
+};
+
+bool ReadUtf8(napi_env env, napi_value value, std::string* out) {
+  size_t length = 0;
+  if (napi_get_value_string_utf8(env, value, nullptr, 0, &length) != napi_ok) {
+    return false;
+  }
+  // Room for the NUL node insists on writing, then cut back to what it says
+  // it wrote.
+  std::string text(length + 1, '\0');
+  size_t written = 0;
+  if (napi_get_value_string_utf8(env, value, text.data(), length + 1,
+                                 &written) != napi_ok) {
+    return false;
+  }
+  text.resize(written);
+  *out = std::move(text);
+  return true;
+}
+
+napi_value Undefined(napi_env env) {
+  napi_value value = nullptr;
+  napi_get_undefined(env, &value);
+  return value;
+}
+
+// Turns a shot_buffer carrying a message into a thrown JS error. Freeing it is
+// this function's job either way, because every caller is on its way out.
+void ThrowFromBuffer(napi_env env, shot_buffer* message, const char* fallback) {
+  const char* text = fallback;
+  if (message && shot_buffer_size(message) > 0) {
+    text = reinterpret_cast<const char*>(shot_buffer_data(message));
+  }
+  napi_throw_error(env, nullptr, text);
+  shot_buffer_free(message);
+}
+
+bool ReadHandle(napi_env env, napi_value value, EngineHandle** out) {
+  void* data = nullptr;
+  if (napi_get_value_external(env, value, &data) != napi_ok || !data) {
+    napi_throw_type_error(env, nullptr, "shotium: expected an engine handle");
+    return false;
+  }
+  *out = static_cast<EngineHandle*>(data);
+  if (!(*out)->engine) {
+    napi_throw_error(env, nullptr, "shotium: this engine has been destroyed");
+    return false;
+  }
+  return true;
+}
+
+napi_value Create(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1] = {};
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+
+  std::string options;
+  if (argc > 0 && !ReadUtf8(env, argv[0], &options)) {
+    napi_throw_type_error(env, nullptr,
+                          "shotium: create(optionsJson) wants a string");
+    return nullptr;
+  }
+
+  if (shot_abi_version() != SHOT_ABI_VERSION) {
+    napi_throw_error(env, nullptr,
+                     "shotium: the shot library beside this addon speaks a "
+                     "different ABI version; they ship together and one of "
+                     "them has been replaced");
+    return nullptr;
+  }
+
+  shot_engine* engine = nullptr;
+  shot_buffer* error = nullptr;
+  if (shot_engine_create(options.c_str(), &engine, &error) != SHOT_OK) {
+    ThrowFromBuffer(env, error, "shotium: the engine would not start");
+    return nullptr;
+  }
+
+  auto* handle = new EngineHandle{engine};
+  napi_value external = nullptr;
+  if (napi_create_external(env, handle, FinalizeEngine, nullptr, &external) !=
+      napi_ok) {
+    shot_engine_destroy(engine);
+    delete handle;
+    napi_throw_error(env, nullptr, "shotium: could not wrap the engine");
+    return nullptr;
+  }
+  return external;
+}
+
+napi_value Destroy(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv[1] = {};
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+
+  void* data = nullptr;
+  if (argc < 1 || napi_get_value_external(env, argv[0], &data) != napi_ok ||
+      !data) {
+    napi_throw_type_error(env, nullptr, "shotium: expected an engine handle");
+    return nullptr;
+  }
+  auto* handle = static_cast<EngineHandle*>(data);
+  if (handle->engine) {
+    shot_engine_destroy(handle->engine);
+    handle->engine = nullptr;
+  }
+  return Undefined(env);
+}
+
+// Runs on a libuv thread. No napi call is legal here beyond the ones that take
+// no env, which is why everything it needs was copied out first.
+void ExecuteCapture(napi_env env, void* data) {
+  auto* task = static_cast<CaptureTask*>(data);
+  task->status = shot_engine_capture(task->engine, task->request.c_str(),
+                                     &task->image, &task->error);
+}
+
+void CompleteCapture(napi_env env, napi_status status, void* data) {
+  auto* task = static_cast<CaptureTask*>(data);
+
+  if (status == napi_ok && task->status == SHOT_OK) {
+    // Copied into a node Buffer rather than handed over as external memory.
+    // An external buffer would save a memcpy of a few hundred kilobytes
+    // against a render that took tens of milliseconds, and would put the
+    // lifetime of shot's allocation in the hands of node's GC -- across an
+    // allocator boundary the whole C ABI exists to keep closed.
+    napi_value buffer = nullptr;
+    napi_create_buffer_copy(env, shot_buffer_size(task->image),
+                            shot_buffer_data(task->image), nullptr, &buffer);
+    napi_resolve_deferred(env, task->deferred, buffer);
+  } else {
+    const char* text = "shotium: the capture failed";
+    if (task->error && shot_buffer_size(task->error) > 0) {
+      text = reinterpret_cast<const char*>(shot_buffer_data(task->error));
+    }
+    napi_value message = nullptr;
+    napi_value error_value = nullptr;
+    napi_create_string_utf8(env, text, NAPI_AUTO_LENGTH, &message);
+    napi_create_error(env, nullptr, message, &error_value);
+    napi_reject_deferred(env, task->deferred, error_value);
+  }
+
+  shot_buffer_free(task->image);
+  shot_buffer_free(task->error);
+  napi_delete_async_work(env, task->work);
+  delete task;
+}
+
+napi_value Capture(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2] = {};
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+
+  EngineHandle* handle = nullptr;
+  if (argc < 2 || !ReadHandle(env, argv[0], &handle)) {
+    return nullptr;
+  }
+
+  auto* task = new CaptureTask;
+  task->engine = handle->engine;
+  if (!ReadUtf8(env, argv[1], &task->request)) {
+    delete task;
+    napi_throw_type_error(env, nullptr,
+                          "shotium: capture(engine, requestJson) wants a "
+                          "string");
+    return nullptr;
+  }
+
+  napi_value promise = nullptr;
+  if (napi_create_promise(env, &task->deferred, &promise) != napi_ok) {
+    delete task;
+    napi_throw_error(env, nullptr, "shotium: could not make a promise");
+    return nullptr;
+  }
+
+  napi_value name = nullptr;
+  napi_create_string_utf8(env, "shot:capture", NAPI_AUTO_LENGTH, &name);
+  napi_create_async_work(env, nullptr, name, ExecuteCapture, CompleteCapture,
+                         task, &task->work);
+  napi_queue_async_work(env, task->work);
+  return promise;
+}
+
+// Synchronous on purpose. A purge is milliseconds and happens when the caller
+// has decided it has nothing else to do; queuing it behind the event loop
+// would mean the process that just went idle stays large until something wakes
+// it up.
+napi_value Purge(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2] = {};
+  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
+
+  EngineHandle* handle = nullptr;
+  if (argc < 1 || !ReadHandle(env, argv[0], &handle)) {
+    return nullptr;
+  }
+
+  bool release = false;
+  if (argc > 1) {
+    napi_get_value_bool(env, argv[1], &release);
+  }
+  shot_engine_purge(handle->engine, release ? 1 : 0);
+  return Undefined(env);
+}
+
+napi_value Init(napi_env env, napi_value exports) {
+  const napi_property_descriptor properties[] = {
+      {"create", nullptr, Create, nullptr, nullptr, nullptr, napi_default,
+       nullptr},
+      {"destroy", nullptr, Destroy, nullptr, nullptr, nullptr, napi_default,
+       nullptr},
+      {"capture", nullptr, Capture, nullptr, nullptr, nullptr, napi_default,
+       nullptr},
+      {"purge", nullptr, Purge, nullptr, nullptr, nullptr, napi_default,
+       nullptr},
+  };
+  napi_define_properties(env, exports,
+                         sizeof(properties) / sizeof(properties[0]),
+                         properties);
+  return exports;
+}
+
+}  // namespace
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

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,63 @@
 {
   "name": "@shotkit/shotium",
-  "version": "0.0.1",
-  "description": "Placeholder release to reserve the package name for Trusted Publishing.",
-  "license": "MIT"
+  "version": "0.1.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"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "default": "./dist/native.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.1.0",
+    "@shotkit/shotium-darwin-x64": "0.1.0",
+    "@shotkit/shotium-linux-arm64": "0.1.0",
+    "@shotkit/shotium-linux-x64": "0.1.0",
+    "@shotkit/shotium-win32-arm64": "0.1.0",
+    "@shotkit/shotium-win32-x64": "0.1.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();