@nitpicker/core 0.24.0 → 0.25.0

package/lib/load-native-binding.js

@@ -0,0 +1,152 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Oldest glibc the Linux addon is built against (the `manylinux_2_28`
+ * release container). Matches the floor of Node.js 24's own Linux binaries,
+ * so any Linux that can run a supported Node can load the addon.
+ */
+const MIN_GLIBC = [2, 28];
+const SUPPORTED_PLATFORMS_MESSAGE = 'Supported platforms: darwin-arm64 (Apple silicon macOS), linux-x64 with glibc >= 2.28 (including WSL2).';
+/**
+ * Prebuilt addon for each supported host: the platform package that ships
+ * it, and its file name (identical inside that package and at the
+ * `@nitpicker/core` root, where a local `yarn build` puts it).
+ */
+const PLATFORM_ADDONS = {
+    'darwin-arm64': {
+        packageName: '@nitpicker/core-darwin-arm64',
+        fileName: 'core.darwin-arm64.node',
+    },
+    'linux-x64': {
+        packageName: '@nitpicker/core-linux-x64-gnu',
+        fileName: 'core.linux-x64-gnu.node',
+    },
+};
+/**
+ * Loads the native addon for the running platform.
+ *
+ * Looks for a locally built `core.<platform>.node` at the package root
+ * first (a monorepo checkout after `yarn build`), then for the prebuilt
+ * platform package installed through `optionalDependencies`. Prebuilt
+ * binaries exist only for darwin-arm64 and linux-x64 (glibc), and there is
+ * no JavaScript fallback, so any other platform fails here with the list of
+ * supported ones instead of a bare `MODULE_NOT_FOUND`.
+ *
+ * Load errors of an addon that does exist (a corrupt or ABI-incompatible
+ * file) are rethrown as-is rather than retried against the other location:
+ * silently picking a different binary would hide the broken one.
+ * @param options - Overrides for the host facts; omitted fields use the
+ *   running process.
+ * @returns The addon's exported functions.
+ * @throws {Error} When the platform is unsupported or the platform package is
+ *   not installed.
+ * @example
+ * ```ts
+ * const binding = loadNativeBinding();
+ * binding.computeBodyHash(Buffer.from('<body>x</body>'));
+ * ```
+ */
+export function loadNativeBinding(options) {
+    const platform = options?.platform ?? process.platform;
+    const arch = options?.arch ?? process.arch;
+    const packageDir = options?.packageDir ??
+        path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const fileExists = options?.fileExists ?? existsSync;
+    const requireModule = options?.requireModule ?? createRequire(import.meta.url);
+    const host = `${platform}-${arch}`;
+    const addon = host in PLATFORM_ADDONS
+        ? PLATFORM_ADDONS[host]
+        : null;
+    if (!addon) {
+        throw new Error(`@nitpicker/core has no prebuilt native addon for ${host}. ${SUPPORTED_PLATFORMS_MESSAGE}`);
+    }
+    if (platform === 'linux') {
+        // Detected only here: building the diagnostic report costs startup time
+        // that macOS (no libc choice) has no reason to pay.
+        const glibcVersion = options?.glibcVersion === undefined ? detectGlibcVersion() : options.glibcVersion;
+        if (glibcVersion === null) {
+            throw new Error(`@nitpicker/core requires glibc on Linux, but this system uses another C library (e.g. musl). ${SUPPORTED_PLATFORMS_MESSAGE}`);
+        }
+        if (!isAtLeast(glibcVersion, MIN_GLIBC)) {
+            throw new Error(`@nitpicker/core requires glibc >= ${MIN_GLIBC.join('.')}, but this system has glibc ${glibcVersion}. ${SUPPORTED_PLATFORMS_MESSAGE}`);
+        }
+    }
+    const localBuild = path.join(packageDir, addon.fileName);
+    if (fileExists(localBuild)) {
+        return requireModule(localBuild);
+    }
+    try {
+        return requireModule(addon.packageName);
+    }
+    catch (error) {
+        // The same error covers a package that is absent and one that is present
+        // without its binary (a source checkout before `yarn build`), so the
+        // message names both fixes instead of guessing.
+        if (isModuleNotFound(error, addon.packageName)) {
+            throw new Error(`@nitpicker/core could not load its native addon from ${addon.packageName}: the package is not installed, or is installed without ${addon.fileName}. ` +
+                'In a source checkout, run `yarn build` (it builds the addon locally). ' +
+                'Otherwise reinstall without --no-optional / --omit=optional, which skip the platform package.', { cause: error });
+        }
+        throw error;
+    }
+}
+/**
+ * The glibc version the process runs against, read from Node's diagnostic
+ * report header (absent under musl).
+ *
+ * Network interfaces are excluded from the report for the call — they are
+ * the slow part of building it and irrelevant here — and the previous
+ * setting is restored so the process's own diagnostic reports are unchanged.
+ * @returns The glibc version string, or `null` when the C library is not glibc.
+ */
+function detectGlibcVersion() {
+    // `excludeNetwork` exists at runtime on every supported Node (>= 24) but is
+    // missing from the installed `@types/node`'s `ProcessReport`.
+    const processReport = process.report;
+    const previous = processReport.excludeNetwork;
+    processReport.excludeNetwork = true;
+    try {
+        const report = processReport.getReport();
+        return report.header?.glibcVersionRuntime ?? null;
+    }
+    finally {
+        processReport.excludeNetwork = previous;
+    }
+}
+/**
+ * Compares a `major.minor` version numerically, so `2.9` is older than
+ * `2.28` (a string comparison would say the opposite).
+ * @param version - Version string such as `"2.35"`.
+ * @param minimum - Required `[major, minor]`.
+ * @returns Whether `version` is at least `minimum`.
+ */
+function isAtLeast(version, minimum) {
+    const [minMajor, minMinor] = minimum;
+    const [major = 0, minor = 0] = version.split('.').map(Number);
+    return major > minMajor || (major === minMajor && minor >= minMinor);
+}
+/**
+ * Whether `error` is Node's `MODULE_NOT_FOUND` for `specifier` itself, as
+ * opposed to a module that `specifier` failed to load in turn.
+ *
+ * Only the first line is compared — the rest of the message is the require
+ * stack, which names the platform package's own files when something inside
+ * it is missing. That line names either the package itself (`Cannot find
+ * module '<specifier>'`, not installed) or a path inside it (`Cannot find
+ * module '…/<specifier>/core.….node'`, installed without its binary).
+ * @param error - The value thrown by `require`.
+ * @param specifier - The specifier that was required.
+ * @returns `true` only for a not-found error whose first line names the
+ *   package or its own `main` file.
+ */
+function isModuleNotFound(error, specifier) {
+    if (!(error instanceof Error) ||
+        !('code' in error) ||
+        error.code !== 'MODULE_NOT_FOUND') {
+        return false;
+    }
+    const [firstLine = ''] = error.message.split('\n');
+    return firstLine.includes(`'${specifier}'`) || firstLine.includes(`/${specifier}/`);
+}

package/lib/match-js-license-comment-signal.d.ts

@@ -0,0 +1,19 @@
+import type { StructuralTechnologySignal } from './types.js';
+/**
+ * Matches the license-banner fingerprints (`js-license-comment`, such as
+ * Vue's leading `/*! * Vue.js v3…` comment) against the leading bytes of a
+ * JS resource, returning the first that occurs. The same definitions
+ * {@link import('./match-structural-technology-signals.js').matchStructuralTechnologySignals}
+ * applies to HTML; the other fingerprints describe HTML and are not tested.
+ * @param script - The resource's leading bytes as fetched. Bytes that are
+ *   not valid UTF-8 (a prefix cut inside a character) read as U+FFFD in the
+ *   evidence, as `Buffer.prototype.toString('utf8')` decodes them.
+ * @returns The first matching signal, or `null` when none matches.
+ * @example
+ * ```ts
+ * matchJsLicenseCommentSignal(Buffer.from('/*!\n * Vue.js v3.4.0\n *\/'));
+ * // { technology: 'Vue', signalType: 'js-license-comment',
+ * //   evidence: '/*!\n * Vue.js v3', weight: 55, category: 'JavaScript frameworks' }
+ * ```
+ */
+export declare function matchJsLicenseCommentSignal(script: Uint8Array): StructuralTechnologySignal | null;

package/lib/match-js-license-comment-signal.js

@@ -0,0 +1,21 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * Matches the license-banner fingerprints (`js-license-comment`, such as
+ * Vue's leading `/*! * Vue.js v3…` comment) against the leading bytes of a
+ * JS resource, returning the first that occurs. The same definitions
+ * {@link import('./match-structural-technology-signals.js').matchStructuralTechnologySignals}
+ * applies to HTML; the other fingerprints describe HTML and are not tested.
+ * @param script - The resource's leading bytes as fetched. Bytes that are
+ *   not valid UTF-8 (a prefix cut inside a character) read as U+FFFD in the
+ *   evidence, as `Buffer.prototype.toString('utf8')` decodes them.
+ * @returns The first matching signal, or `null` when none matches.
+ * @example
+ * ```ts
+ * matchJsLicenseCommentSignal(Buffer.from('/*!\n * Vue.js v3.4.0\n *\/'));
+ * // { technology: 'Vue', signalType: 'js-license-comment',
+ * //   evidence: '/*!\n * Vue.js v3', weight: 55, category: 'JavaScript frameworks' }
+ * ```
+ */
+export function matchJsLicenseCommentSignal(script) {
+    return nativeBinding.matchJsLicenseCommentSignal(script);
+}

package/lib/match-selector-html.d.ts

@@ -0,0 +1,41 @@
+import type { HtmlMatchOutcome, SelectorPlan } from './types.js';
+/**
+ * Decides whether any element of one stored HTML document matches a planned
+ * selector list, using the cheapest stage that is exact: an ordered-literal
+ * prefilter, then the start tags alone for selectors one tag decides, then
+ * an open-element stack.
+ *
+ * The result is a judgement about the stored string read as markup with
+ * balanced tags (the interpretation rules are in `@nitpicker/cli`'s
+ * `docs/query.md`), not a DOM query: serialization is not injective, so it
+ * is not guaranteed to equal the verdict on the DOM the string came from.
+ * Tag and attribute names ignore ASCII case only.
+ * @param options - The plan and the document.
+ * @param options.plan - The validated selector list.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @returns The verdict, which stages ran, and how many elements the stack tested.
+ * @throws {Error} With code `InvalidArg` if the plan is malformed.
+ * @example
+ * ```ts
+ * const { matched } = matchSelectorHtml({
+ * 	plan: {
+ * 		alternatives: [
+ * 			{
+ * 				compounds: [{ tag: 'img', attributes: [], nth: [], negations: [] }],
+ * 				combinators: [],
+ * 				prefilterLiterals: ['<img'],
+ * 				direct: true,
+ * 			},
+ * 		],
+ * 		needsChildIndex: false,
+ * 		needsTypeIndex: false,
+ * 	},
+ * 	html: '<p><img src="a.png"></p>',
+ * });
+ * matched; // true
+ * ```
+ */
+export declare function matchSelectorHtml(options: {
+    readonly plan: SelectorPlan;
+    readonly html: string | Uint8Array;
+}): HtmlMatchOutcome;

package/lib/match-selector-html.js

@@ -0,0 +1,42 @@
+import { nativeBinding } from './native-binding.js';
+import { toNativeSelectorPlan } from './to-native-selector-plan.js';
+/**
+ * Decides whether any element of one stored HTML document matches a planned
+ * selector list, using the cheapest stage that is exact: an ordered-literal
+ * prefilter, then the start tags alone for selectors one tag decides, then
+ * an open-element stack.
+ *
+ * The result is a judgement about the stored string read as markup with
+ * balanced tags (the interpretation rules are in `@nitpicker/cli`'s
+ * `docs/query.md`), not a DOM query: serialization is not injective, so it
+ * is not guaranteed to equal the verdict on the DOM the string came from.
+ * Tag and attribute names ignore ASCII case only.
+ * @param options - The plan and the document.
+ * @param options.plan - The validated selector list.
+ * @param options.html - The stored markup, as a string or as UTF-8 bytes.
+ * @returns The verdict, which stages ran, and how many elements the stack tested.
+ * @throws {Error} With code `InvalidArg` if the plan is malformed.
+ * @example
+ * ```ts
+ * const { matched } = matchSelectorHtml({
+ * 	plan: {
+ * 		alternatives: [
+ * 			{
+ * 				compounds: [{ tag: 'img', attributes: [], nth: [], negations: [] }],
+ * 				combinators: [],
+ * 				prefilterLiterals: ['<img'],
+ * 				direct: true,
+ * 			},
+ * 		],
+ * 		needsChildIndex: false,
+ * 		needsTypeIndex: false,
+ * 	},
+ * 	html: '<p><img src="a.png"></p>',
+ * });
+ * matched; // true
+ * ```
+ */
+export function matchSelectorHtml(options) {
+    const { plan, html } = options;
+    return nativeBinding.matchSelectorHtml(toNativeSelectorPlan(plan), typeof html === 'string' ? Buffer.from(html, 'utf8') : html);
+}

package/lib/match-selector-snapshots.d.ts

@@ -0,0 +1,40 @@
+import type { SelectorPlan, SnapshotMatchOutcome, StoredHtmlSnapshot } from './types.js';
+/**
+ * Judges a batch of stored HTML snapshots against a planned selector list.
+ *
+ * Each snapshot is decompressed, read as UTF-8 (an invalid sequence becomes
+ * U+FFFD, as `Buffer#toString('utf8')` reads it) and judged by
+ * {@link import('./match-selector-html.js').matchSelectorHtml}'s rules, in
+ * parallel on the native thread pool. No more decompressed documents are
+ * alive at once than there are threads. The call waits its turn behind any
+ * other asynchronous native call when `NITPICKER_NATIVE_CONCURRENCY` calls are
+ * already running (see `checkNativeExecutorConfig`). Only the batch's stored bytes cross
+ * the boundary, as one buffer and one offsets array.
+ *
+ * A snapshot that cannot be decompressed — its zstd data is corrupt, or it
+ * decompresses past `MAX_DECODED_SNAPSHOT_BYTES` — fails the whole call; it is
+ * never judged "no match".
+ * @param options - The plan and the batch.
+ * @param options.plan - The validated selector list.
+ * @param options.snapshots - The stored snapshots, in the order the verdicts are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One verdict per snapshot, in input order.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects with a plain error naming the snapshot
+ *   (`snapshot <n> could not be decoded`) if its zstd data is corrupt or
+ *   decompresses past the limit, and with the signal's reason if `signal`
+ *   aborted before the call finished.
+ * @example
+ * ```ts
+ * const verdicts = await matchSelectorSnapshots({
+ * 	plan,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * const matchedCount = verdicts.filter((verdict) => verdict.matched).length;
+ * ```
+ */
+export declare function matchSelectorSnapshots(options: {
+    readonly plan: SelectorPlan;
+    readonly snapshots: readonly StoredHtmlSnapshot[];
+    readonly signal?: AbortSignal;
+}): Promise<SnapshotMatchOutcome[]>;

package/lib/match-selector-snapshots.js

@@ -0,0 +1,57 @@
+import { MAX_DECODED_SNAPSHOT_BYTES } from './max-decoded-snapshot-bytes.js';
+import { nativeBinding } from './native-binding.js';
+import { packStoredSnapshots } from './pack-stored-snapshots.js';
+import { runWithSignal } from './run-with-signal.js';
+import { toNativeSelectorPlan } from './to-native-selector-plan.js';
+/** Bit 0 of a verdict byte the native call returns: an element matched. */
+const MATCHED = 1;
+/** Bit 1: the ordered-literal prefilter rejected the document alone. */
+const PREFILTERED = 2;
+/** Bit 2: the open-element stack judged the document. */
+const TOKENIZED = 4;
+/**
+ * Judges a batch of stored HTML snapshots against a planned selector list.
+ *
+ * Each snapshot is decompressed, read as UTF-8 (an invalid sequence becomes
+ * U+FFFD, as `Buffer#toString('utf8')` reads it) and judged by
+ * {@link import('./match-selector-html.js').matchSelectorHtml}'s rules, in
+ * parallel on the native thread pool. No more decompressed documents are
+ * alive at once than there are threads. The call waits its turn behind any
+ * other asynchronous native call when `NITPICKER_NATIVE_CONCURRENCY` calls are
+ * already running (see `checkNativeExecutorConfig`). Only the batch's stored bytes cross
+ * the boundary, as one buffer and one offsets array.
+ *
+ * A snapshot that cannot be decompressed — its zstd data is corrupt, or it
+ * decompresses past `MAX_DECODED_SNAPSHOT_BYTES` — fails the whole call; it is
+ * never judged "no match".
+ * @param options - The plan and the batch.
+ * @param options.plan - The validated selector list.
+ * @param options.snapshots - The stored snapshots, in the order the verdicts are returned.
+ * @param options.signal - Stops the call at its next snapshot, or within the next mebibyte of a decompression under way; a call still waiting for its turn stops when the turn comes.
+ * @returns One verdict per snapshot, in input order.
+ * @throws {Error} If a codec is not `zstd` or `none`, or the batch takes more than 4 GiB.
+ *   The returned promise rejects with a plain error naming the snapshot
+ *   (`snapshot <n> could not be decoded`) if its zstd data is corrupt or
+ *   decompresses past the limit, and with the signal's reason if `signal`
+ *   aborted before the call finished.
+ * @example
+ * ```ts
+ * const verdicts = await matchSelectorSnapshots({
+ * 	plan,
+ * 	snapshots: rows.map((row) => ({ body: row.body, codec: row.codec })),
+ * });
+ * const matchedCount = verdicts.filter((verdict) => verdict.matched).length;
+ * ```
+ */
+export async function matchSelectorSnapshots(options) {
+    const { plan, snapshots, signal } = options;
+    // Before packing: a request that is already cancelled copies nothing.
+    signal?.throwIfAborted();
+    const { bodies, offsets, codecs } = packStoredSnapshots(snapshots);
+    const flags = await runWithSignal(signal, (cancelToken) => nativeBinding.matchSelectorSnapshots(toNativeSelectorPlan(plan), bodies, offsets, codecs, MAX_DECODED_SNAPSHOT_BYTES, cancelToken));
+    return [...flags].map((flag) => ({
+        matched: (flag & MATCHED) !== 0,
+        prefiltered: (flag & PREFILTERED) !== 0,
+        tokenized: (flag & TOKENIZED) !== 0,
+    }));
+}

package/lib/match-structural-technology-signals.d.ts

@@ -0,0 +1,23 @@
+import type { StructuralTechnologySignal } from './types.js';
+/**
+ * Matches the fixed list of frontend-framework fingerprints (Next.js,
+ * Astro, Vue, Nuxt, Svelte, SvelteKit, Remix, Gatsby, Angular — HTML
+ * markers, URL path fragments, scoped attributes, license banners) against
+ * a page's HTML, returning one signal per fingerprint found, in the list's
+ * order, with the evidence cut from its first match.
+ *
+ * The list lives in `crates/nitpicker_tech_detect`. Its output equals what
+ * the JavaScript regular expressions it was ported from stored into
+ * existing archives' `technology_signals`, so old and new crawls stay
+ * comparable. Takes UTF-8 bytes so the native side never builds a UTF-16
+ * copy, and scans the page once for all fingerprints.
+ * @param html - The page's HTML as UTF-8 bytes — `Buffer.from(html, 'utf8')`.
+ * @returns The signals found; empty when the page shows no fingerprint.
+ * @example
+ * ```ts
+ * matchStructuralTechnologySignals(Buffer.from('<div data-v-1a2b3c4d></div>'));
+ * // [{ technology: 'Vue', signalType: 'scoped-attr', evidence: ' data-v-1a2b3c4d',
+ * //    weight: 40, category: 'JavaScript frameworks' }]
+ * ```
+ */
+export declare function matchStructuralTechnologySignals(html: Uint8Array): StructuralTechnologySignal[];

package/lib/match-structural-technology-signals.js

@@ -0,0 +1,25 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * Matches the fixed list of frontend-framework fingerprints (Next.js,
+ * Astro, Vue, Nuxt, Svelte, SvelteKit, Remix, Gatsby, Angular — HTML
+ * markers, URL path fragments, scoped attributes, license banners) against
+ * a page's HTML, returning one signal per fingerprint found, in the list's
+ * order, with the evidence cut from its first match.
+ *
+ * The list lives in `crates/nitpicker_tech_detect`. Its output equals what
+ * the JavaScript regular expressions it was ported from stored into
+ * existing archives' `technology_signals`, so old and new crawls stay
+ * comparable. Takes UTF-8 bytes so the native side never builds a UTF-16
+ * copy, and scans the page once for all fingerprints.
+ * @param html - The page's HTML as UTF-8 bytes — `Buffer.from(html, 'utf8')`.
+ * @returns The signals found; empty when the page shows no fingerprint.
+ * @example
+ * ```ts
+ * matchStructuralTechnologySignals(Buffer.from('<div data-v-1a2b3c4d></div>'));
+ * // [{ technology: 'Vue', signalType: 'scoped-attr', evidence: ' data-v-1a2b3c4d',
+ * //    weight: 40, category: 'JavaScript frameworks' }]
+ * ```
+ */
+export function matchStructuralTechnologySignals(html) {
+    return nativeBinding.matchStructuralTechnologySignals(html);
+}

package/lib/max-decoded-snapshot-bytes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bytes one zstd-compressed HTML snapshot may decompress to (3 × (2^29 − 24),
+ * about 1.5 GiB). A snapshot that decompresses past it is reported as
+ * undecodable instead of being held whole: the size a zstd frame header
+ * states can be absent or false, so a stored blob of a few kilobytes can
+ * otherwise expand to any size, on every thread of a batch at once (RFC 8878,
+ * §8). A snapshot stored uncompressed is not limited — it is already in
+ * memory at its size.
+ *
+ * The value is the most the crawler can store, so no snapshot it stored is
+ * ever refused: a snapshot is the string `page.content()` returns, saved as
+ * UTF-8, a V8 string holds at most 2^29 − 24 UTF-16 code units, and one code
+ * unit takes at most 3 bytes of UTF-8. Read from the addon, which owns the value; the
+ * batch wrappers pass this module's export back to it, so a spec can shrink
+ * it. An addon that lacks it fails the import rather than leaving
+ * `maxOutputLength` undefined, which would decompress without a limit.
+ * @example
+ * ```ts
+ * zstdDecompressSync(body, { maxOutputLength: MAX_DECODED_SNAPSHOT_BYTES });
+ * ```
+ */
+export declare const MAX_DECODED_SNAPSHOT_BYTES: number;

package/lib/max-decoded-snapshot-bytes.js

@@ -0,0 +1,35 @@
+import { nativeBinding } from './native-binding.js';
+/**
+ * The addon's limit, checked to be a positive integer.
+ * @returns The limit in bytes.
+ * @throws {TypeError} If the addon does not export it.
+ */
+function readLimit() {
+    const limit = nativeBinding.MAX_DECODED_SNAPSHOT_BYTES;
+    if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit <= 0) {
+        throw new TypeError(`The native addon exports no valid MAX_DECODED_SNAPSHOT_BYTES (got ${String(limit)}); rebuild or reinstall @nitpicker/core.`);
+    }
+    return limit;
+}
+/**
+ * Bytes one zstd-compressed HTML snapshot may decompress to (3 × (2^29 − 24),
+ * about 1.5 GiB). A snapshot that decompresses past it is reported as
+ * undecodable instead of being held whole: the size a zstd frame header
+ * states can be absent or false, so a stored blob of a few kilobytes can
+ * otherwise expand to any size, on every thread of a batch at once (RFC 8878,
+ * §8). A snapshot stored uncompressed is not limited — it is already in
+ * memory at its size.
+ *
+ * The value is the most the crawler can store, so no snapshot it stored is
+ * ever refused: a snapshot is the string `page.content()` returns, saved as
+ * UTF-8, a V8 string holds at most 2^29 − 24 UTF-16 code units, and one code
+ * unit takes at most 3 bytes of UTF-8. Read from the addon, which owns the value; the
+ * batch wrappers pass this module's export back to it, so a spec can shrink
+ * it. An addon that lacks it fails the import rather than leaving
+ * `maxOutputLength` undefined, which would decompress without a limit.
+ * @example
+ * ```ts
+ * zstdDecompressSync(body, { maxOutputLength: MAX_DECODED_SNAPSHOT_BYTES });
+ * ```
+ */
+export const MAX_DECODED_SNAPSHOT_BYTES = readLimit();

package/lib/native-binding.d.ts

@@ -0,0 +1,9 @@
+import type { NativeBinding } from './types.js';
+/**
+ * The native addon, loaded once when this module is first imported.
+ *
+ * Loaded eagerly rather than on first call so an unsupported platform fails
+ * at CLI startup with the supported-platform list, not halfway through a
+ * crawl when the first page is hashed.
+ */
+export declare const nativeBinding: NativeBinding;

package/lib/native-binding.js

@@ -0,0 +1,9 @@
+import { loadNativeBinding } from './load-native-binding.js';
+/**
+ * The native addon, loaded once when this module is first imported.
+ *
+ * Loaded eagerly rather than on first call so an unsupported platform fails
+ * at CLI startup with the supported-platform list, not halfway through a
+ * crawl when the first page is hashed.
+ */
+export const nativeBinding = loadNativeBinding();

package/lib/pack-stored-snapshots.d.ts

@@ -0,0 +1,23 @@
+import type { StoredHtmlSnapshot } from './types.js';
+/**
+ * Lays a batch of stored snapshots out the way the native batch calls take
+ * it: the stored bytes back to back, the `n + 1` offsets that cut them into
+ * `n` snapshots, and one codec byte per snapshot. A batch crosses the
+ * boundary as three buffers, whatever its size.
+ * @param snapshots - The stored snapshots, in the order the results come back.
+ * @returns The three buffers.
+ * @throws {Error} If a codec is not `zstd` or `none`.
+ * @throws {RangeError} If the batch takes more than 4 GiB.
+ * @example
+ * ```ts
+ * const { bodies, offsets, codecs } = packStoredSnapshots([
+ * 	{ body: Buffer.from('<p>a</p>'), codec: 'none' },
+ * ]);
+ * offsets; // Uint32Array [0, 8]
+ * ```
+ */
+export declare function packStoredSnapshots(snapshots: readonly StoredHtmlSnapshot[]): {
+    readonly bodies: Uint8Array;
+    readonly offsets: Uint32Array;
+    readonly codecs: Uint8Array;
+};

package/lib/pack-stored-snapshots.js

@@ -0,0 +1,53 @@
+/** The native calls address a batch with `u32` offsets. */
+const MAX_BATCH_BYTES = 4_294_967_295;
+/** The codec byte the native calls read for a snapshot stored as it is. */
+const CODEC_NONE = 0;
+/** The codec byte the native calls read for a zstd snapshot. */
+const CODEC_ZSTD = 1;
+/**
+ * Lays a batch of stored snapshots out the way the native batch calls take
+ * it: the stored bytes back to back, the `n + 1` offsets that cut them into
+ * `n` snapshots, and one codec byte per snapshot. A batch crosses the
+ * boundary as three buffers, whatever its size.
+ * @param snapshots - The stored snapshots, in the order the results come back.
+ * @returns The three buffers.
+ * @throws {Error} If a codec is not `zstd` or `none`.
+ * @throws {RangeError} If the batch takes more than 4 GiB.
+ * @example
+ * ```ts
+ * const { bodies, offsets, codecs } = packStoredSnapshots([
+ * 	{ body: Buffer.from('<p>a</p>'), codec: 'none' },
+ * ]);
+ * offsets; // Uint32Array [0, 8]
+ * ```
+ */
+export function packStoredSnapshots(snapshots) {
+    const offsets = new Uint32Array(snapshots.length + 1);
+    const codecs = new Uint8Array(snapshots.length);
+    let total = 0;
+    for (const [index, snapshot] of snapshots.entries()) {
+        switch (snapshot.codec) {
+            case 'none': {
+                codecs[index] = CODEC_NONE;
+                break;
+            }
+            case 'zstd': {
+                codecs[index] = CODEC_ZSTD;
+                break;
+            }
+            default: {
+                throw new Error(`Unknown page_html_blobs.codec: ${snapshot.codec}`);
+            }
+        }
+        total += snapshot.body.byteLength;
+        if (total > MAX_BATCH_BYTES) {
+            throw new RangeError(`The batch takes more than ${MAX_BATCH_BYTES} bytes (4 GiB), which the native call cannot address.`);
+        }
+        offsets[index + 1] = total;
+    }
+    const bodies = new Uint8Array(total);
+    for (const [index, snapshot] of snapshots.entries()) {
+        bodies.set(snapshot.body, offsets[index]);
+    }
+    return { bodies, offsets, codecs };
+}

package/lib/run-with-signal.d.ts

@@ -0,0 +1,27 @@
+import type { NativeCancelToken } from './types.js';
+/**
+ * Runs one asynchronous native call so an `AbortSignal` can stop it.
+ *
+ * With no signal, `run` gets no token and nothing is allocated. With one, a
+ * fresh native token is raised when the signal fires, and the call stops at
+ * its next check (between snapshots, between mebibytes of a snapshot's
+ * decompression, or when it leaves the queue) and rejects
+ * with code `Cancelled`; that rejection, and only that one, is replaced by
+ * the signal's reason, so an abort reads as the caller's own abort. The
+ * addon reports a cancellation over a decode failure of the same batch (the
+ * caller asked to stop); a batch whose failure came before any snapshot saw
+ * the abort still rejects with that failure, which is passed on unchanged.
+ * A signal that is already aborted rejects with its reason without calling
+ * the addon.
+ * @param signal - The caller's signal, if any.
+ * @param run - Starts the native call, passing the token as its last argument.
+ * @returns What `run` resolved with.
+ * @throws {unknown} The signal's reason when the signal aborted before or during the call.
+ * @example
+ * ```ts
+ * const flags = await runWithSignal(signal, (token) =>
+ * 	nativeBinding.matchSelectorSnapshots(plan, bodies, offsets, codecs, maxDecodedBytes, token),
+ * );
+ * ```
+ */
+export declare function runWithSignal<T>(signal: AbortSignal | undefined, run: (token?: NativeCancelToken) => Promise<T>): Promise<T>;