clearcote 0.21.0 → 0.22.1

package/dist/profileauto.js

@@ -0,0 +1,182 @@
+// `profile: "auto"` — resolve a persona from the best source available.
+//
+// ORDER: the licensed clearcote service first, a local imported directory as backup.
+//
+// The service is preferred because its corpus is fresher, larger and curated. But it can be
+// unreachable for reasons that are none of the caller's fault — no license, an exhausted daily
+// budget, a rate limit, a network blip, an outage — and in every one of those cases a local
+// profile is enormously better than no persona. So the fallback is by design, not a patch.
+//
+// THE FALLBACK IS ALWAYS ANNOUNCED. A silent downgrade would leave a caller believing they are
+// on a fresh service profile while they are on a stale local one, and the whole product is about
+// knowing exactly what identity you are presenting. `source` is returned on every result and a
+// one-line reason is written to stderr unless `quiet`.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PROFILE_DIR } from "./profile.js";
+import { importDirectory, loadImportedProfile } from "./profileimport.js";
+import { selectProfile } from "./profilelib.js";
+import { fetchIndex, fetchProfile } from "./profilesource.js";
+import { ensureLocalProfiles, hasLocalProfiles } from "./profilefetch.js";
+/** Where an imported (e.g. converted chrome-fingerprints) directory is looked for by default. */
+export const DEFAULT_LOCAL_DIR = process.env.CLEARCOTE_PROFILE_SOURCE ?? join(homedir(), ".clearcote", "profiles", "imported");
+/**
+ * First engine major that implements `--fingerprint-profile`.
+ *
+ * BACKWARDS COMPATIBILITY, AND WHY THIS IS A HARD GATE. The free 149 build ships a 15-patch
+ * stack with no persona-profile patch at all, so it does not merely apply the profile badly —
+ * it ignores the switch entirely. Chromium discards unknown switches silently, so a 149 user
+ * who asked for a profile would launch with NO persona while believing they had one. That is
+ * strictly worse than the seed farbling 149 does support, because the failure is invisible.
+ *
+ * So a profile is never sent to an engine that cannot read it. Callers on such an engine fall
+ * back to the seed path, which is what 149 was built for.
+ */
+export const MIN_PROFILE_ENGINE_MAJOR = 150;
+/** Whether this engine can actually apply an imported profile. */
+export function engineSupportsProfiles(browserMajor) {
+    return Number.isFinite(browserMajor) && browserMajor >= MIN_PROFILE_ENGINE_MAJOR;
+}
+function localCachePath() {
+    const d = join(PROFILE_DIR, "library");
+    if (!existsSync(d))
+        mkdirSync(d, { recursive: true });
+    return join(d, "local-index.json");
+}
+export function loadLocalIndex(dir) {
+    const mtimeMs = statSync(dir).mtimeMs;
+    const path = localCachePath();
+    if (existsSync(path)) {
+        try {
+            const c = JSON.parse(readFileSync(path, "utf8"));
+            if (c.dir === dir && c.mtimeMs === mtimeMs)
+                return c.index;
+        }
+        catch {
+            /* fall through and re-index */
+        }
+    }
+    const { index } = importDirectory(dir);
+    try {
+        writeFileSync(path, JSON.stringify({ dir, mtimeMs, index }));
+    }
+    catch {
+        /* a cache write failure must never fail a launch */
+    }
+    return index;
+}
+function note(quiet, msg) {
+    if (!quiet)
+        process.stderr.write(`[clearcote] [profile] ${msg}\n`);
+}
+/** The optional-backup tip is worth saying once, not on every launch. */
+let hintedThisProcess = false;
+/** Test seam: reset the once-per-process tip. */
+export function _resetHint() {
+    hintedThisProcess = false;
+}
+/**
+ * How to populate a local backup directory. Printed when the service is unavailable and no local
+ * directory exists — the moment the caller actually needs it.
+ *
+ * OPTIONAL, AND NOT SOMETHING WE SHIP. Clearcote redistributes no third-party fingerprints; the
+ * dataset is fetched by the user from its own repository under its own terms, and we only read
+ * the converted format. Any directory of clearcote-profile JSON works just as well, which is
+ * why this is phrased as one example rather than the required path.
+ */
+export function localSetupHint(dir) {
+    return [
+        `A local profile directory is optional, and gives "auto" a backup when the service is`,
+        `unavailable. Any folder of clearcote-profile JSON works — your own captures, or a`,
+        `third-party dataset you convert yourself. For example, using the open chrome-fingerprints`,
+        `dataset (fetched by you, from its own repo, under its own licence):`,
+        ``,
+        `    pip install chrome-fingerprints`,
+        `    python tools/fingerprint-collect/convert_dataset.py --out "${dir}" --count 500`,
+        ``,
+        `Or capture your own with tools/fingerprint-collect (collect.html), or point`,
+        `CLEARCOTE_PROFILE_SOURCE at a directory you already have.`,
+    ].join("\n");
+}
+/** Resolve a persona from the local imported directory. */
+export function resolveLocal(host, opts = {}) {
+    const dir = opts.localDir ?? DEFAULT_LOCAL_DIR;
+    if (!existsSync(dir)) {
+        throw new Error(`no local profile directory at ${dir}\n\n${localSetupHint(dir)}`);
+    }
+    const index = loadLocalIndex(dir);
+    if (index.length === 0) {
+        throw new Error(`local profile directory ${dir} contains no usable clearcote-profile JSON`);
+    }
+    const selection = selectProfile(index, host, opts);
+    return { profile: loadImportedProfile(dir, selection.entry.id), selection, source: "local" };
+}
+/**
+ * Resolve `profile: "auto"`: service first, local directory as backup.
+ *
+ * Any service failure falls back — including 401 (no license) and 429 (rate limited or daily
+ * distinct budget exhausted), because in all of those a local persona is better than none and
+ * far better than a hard launch failure.
+ */
+export async function resolveAuto(host, opts = {}) {
+    if (opts.preferLocal) {
+        const r = resolveLocal(host, opts);
+        note(opts.quiet, `using local profile ${r.selection.entry.id} (preferLocal)`);
+        return r;
+    }
+    try {
+        const index = await fetchIndex(host, opts);
+        if (index.length === 0)
+            throw new Error("service returned no candidates for this host");
+        const selection = selectProfile(index, host, opts);
+        const profile = await fetchProfile(selection.entry.id, opts);
+        note(opts.quiet, `using service profile ${selection.entry.id} ` +
+            `(score ${selection.score.toFixed(2)}, pool ${selection.poolSize}, mode ${selection.mode})`);
+        // Mention the optional backup ONCE per process, and only while there is none configured.
+        // The useful moment to learn about a fallback is before you need it — but repeating it on
+        // every launch would be noise, and nagging someone who already set one up would be wrong.
+        if (!hintedThisProcess && !existsSync(opts.localDir ?? DEFAULT_LOCAL_DIR)) {
+            hintedThisProcess = true;
+            note(opts.quiet, `tip: no local backup directory configured. If the service is ever rate limited or
+unreachable, "auto" fails rather than falling back. Setting one up is optional:
+${localSetupHint(opts.localDir ?? DEFAULT_LOCAL_DIR)}`);
+        }
+        return { profile, selection, source: "service" };
+    }
+    catch (serviceErr) {
+        const reason = String(serviceErr instanceof Error ? serviceErr.message : serviceErr).slice(0, 200);
+        // First-run bootstrap: if there is no local library yet, try to build one before giving up.
+        // Only on the fallback path — a working service must never pay for this. Never throws: a
+        // bootstrap failure has to degrade to "no local backup", not take down the launch.
+        if (opts.autoDownload !== false) {
+            const dir = opts.localDir ?? DEFAULT_LOCAL_DIR;
+            if (!hasLocalProfiles(dir)) {
+                await ensureLocalProfiles(dir, join(PROFILE_DIR, "library"), {
+                    quiet: opts.quiet,
+                    count: opts.autoDownloadCount,
+                    converter: opts.converter,
+                    python: opts.python,
+                }).catch(() => false);
+            }
+        }
+        try {
+            const r = resolveLocal(host, opts);
+            // Both halves of the story: what failed, and what is being used instead.
+            note(opts.quiet, `service unavailable (${reason}) — falling back to local profile ${r.selection.entry.id}`);
+            return { ...r, fallbackReason: reason };
+        }
+        catch (localErr) {
+            const dir = opts.localDir ?? DEFAULT_LOCAL_DIR;
+            const noLocalDir = !existsSync(dir);
+            const lr = String(localErr instanceof Error ? localErr.message : localErr);
+            // Report BOTH failures. Surfacing only the local one would send the caller to go and fix
+            // a directory when the real problem was an expired license.
+            throw new Error(`profile: "auto" could not resolve a persona.\n` +
+                `  service: ${reason}\n` +
+                `  local:   ${noLocalDir ? `no directory at ${dir}` : lr}\n\n` +
+                (noLocalDir ? localSetupHint(dir) : ""));
+        }
+    }
+}
+//# sourceMappingURL=profileauto.js.map

package/dist/profileauto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileauto.js","sourceRoot":"","sources":["../src/profileauto.ts"],"names":[],"mappings":"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"}

package/dist/profilefetch.d.ts

@@ -0,0 +1,21 @@
+export interface BootstrapOptions {
+    /** How many profiles to convert. The full set is 10,000; a few hundred is ample for rotation. */
+    count?: number;
+    /** Path to convert_dataset.py. Defaults to the copy in this checkout, if present. */
+    converter?: string;
+    /** Python executable. */
+    python?: string;
+    quiet?: boolean;
+}
+/** True when the directory already holds at least one profile — the cheap check that makes this
+ *  a no-op on every run after the first. */
+export declare function hasLocalProfiles(dir: string): boolean;
+/**
+ * Populate `dir` with converted profiles, if it is empty.
+ *
+ * Returns true when profiles are present afterwards. Never throws for an ordinary missing
+ * prerequisite (no Python, no converter, no network) — the caller is a FALLBACK path, and a
+ * bootstrap failure there must degrade to "no local backup", not take down the launch.
+ */
+export declare function ensureLocalProfiles(dir: string, cacheDir: string, opts?: BootstrapOptions): Promise<boolean>;
+//# sourceMappingURL=profilefetch.d.ts.map

package/dist/profilefetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profilefetch.d.ts","sourceRoot":"","sources":["../src/profilefetch.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD;4CAC4C;AAC5C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMrD;AAkBD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAuClB"}

package/dist/profilefetch.js

@@ -0,0 +1,124 @@
+// Optional first-run bootstrap for the local profile directory.
+//
+// WE DOWNLOAD, WE DO NOT REDISTRIBUTE — and here that distinction is legal, not stylistic.
+// The chrome-fingerprints dataset is **GPL-3.0**. Clearcote's SDK is BSD-3-Clause, so shipping
+// those records inside the package would mean distributing GPL data from a permissively licensed
+// artifact. Fetching it onto the user's own machine, from the upstream repository, at the user's
+// request, is an entirely different act: no redistribution occurs and the dataset's terms are
+// between the user and upstream.
+//
+// This mirrors what geoip.ts already does for the geoip-all-in-one MaxMind database, which is
+// GPL-3.0 for exactly the same reason and is likewise downloaded on first use and never bundled.
+//
+// WHY IT SHELLS OUT TO PYTHON. The dataset is `fingerprints.json.xz` (LZMA — Node has no built-in
+// decompressor) with strings INTERNED as integer indices into a 137 KB `vars.py`. Converting it
+// means resolving that interning and remapping ~157 WebGL keys and ~108 audio keys onto the
+// clearcote-profile schema. tools/fingerprint-collect/convert_dataset.py already does all of
+// that, is tested, and is the file that gets updated when either schema moves. Reimplementing it
+// in TypeScript (and again in C#) would be three copies of one mapping table drifting apart, plus
+// an LZMA dependency in each. Python is a soft requirement for one optional bootstrap step.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const RAW_BASE = "https://raw.githubusercontent.com/Vinyzu/chrome-fingerprints/main/chrome_fingerprints";
+/** The two files convert_dataset.py's find_dataset() looks for. */
+const DATASET_FILES = ["fingerprints.json.xz", "vars.py"];
+function note(quiet, msg) {
+    if (!quiet)
+        process.stderr.write(`[clearcote] [profile] ${msg}\n`);
+}
+/** True when the directory already holds at least one profile — the cheap check that makes this
+ *  a no-op on every run after the first. */
+export function hasLocalProfiles(dir) {
+    try {
+        return existsSync(dir) && readdirSync(dir).some((f) => f.endsWith(".json"));
+    }
+    catch {
+        return false;
+    }
+}
+async function download(url, dest) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`${url} -> HTTP ${res.status}`);
+    writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+}
+function run(cmd, args) {
+    return new Promise((resolve) => {
+        const p = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        p.stderr?.on("data", (d) => { stderr += String(d); });
+        p.on("error", () => resolve({ code: -1, stderr: `could not run ${cmd}` }));
+        p.on("close", (code) => resolve({ code: code ?? -1, stderr }));
+    });
+}
+/**
+ * Populate `dir` with converted profiles, if it is empty.
+ *
+ * Returns true when profiles are present afterwards. Never throws for an ordinary missing
+ * prerequisite (no Python, no converter, no network) — the caller is a FALLBACK path, and a
+ * bootstrap failure there must degrade to "no local backup", not take down the launch.
+ */
+export async function ensureLocalProfiles(dir, cacheDir, opts = {}) {
+    if (hasLocalProfiles(dir))
+        return true;
+    const converter = opts.converter ?? defaultConverterPath();
+    if (!converter || !existsSync(converter)) {
+        note(opts.quiet, "no local profiles and no convert_dataset.py found — skipping bootstrap");
+        return false;
+    }
+    const python = opts.python ?? (process.platform === "win32" ? "python" : "python3");
+    const count = opts.count ?? 500;
+    try {
+        const dataset = join(cacheDir, "chrome-fingerprints");
+        mkdirSync(dataset, { recursive: true });
+        // Fetch the dataset itself rather than requiring `pip install chrome-fingerprints`: these are
+        // the only two files the converter needs, and this keeps the prerequisite to "Python exists".
+        const missing = DATASET_FILES.filter((f) => !existsSync(join(dataset, f)));
+        if (missing.length) {
+            note(opts.quiet, `downloading the chrome-fingerprints dataset (GPL-3.0, ~1.3 MB) from its upstream repo — ` +
+                `not redistributed by clearcote`);
+            for (const f of missing)
+                await download(`${RAW_BASE}/${f}`, join(dataset, f));
+        }
+        mkdirSync(dir, { recursive: true });
+        note(opts.quiet, `converting ${count} profiles into ${dir} (first run only)`);
+        const r = await run(python, [converter, "--dataset", dataset, "--out", dir, "--count", String(count)]);
+        if (r.code !== 0) {
+            note(opts.quiet, `bootstrap failed (${python} exited ${r.code}): ${r.stderr.trim().slice(0, 200)}`);
+            return hasLocalProfiles(dir);
+        }
+        const ok = hasLocalProfiles(dir);
+        note(opts.quiet, ok ? `local profile library ready: ${dir}` : "converter produced no profiles");
+        return ok;
+    }
+    catch (e) {
+        note(opts.quiet, `bootstrap skipped: ${String(e instanceof Error ? e.message : e).slice(0, 160)}`);
+        return false;
+    }
+}
+/**
+ * convert_dataset.py inside this checkout, when the SDK is used from the repo.
+ *
+ * Returns null rather than throwing for ANY reason. This is called from a fallback path, and the
+ * published package has no `tools/` directory at all — an installed-from-npm user simply has no
+ * converter, which is a normal state and not an error.
+ */
+function defaultConverterPath() {
+    try {
+        const env = process.env.CLEARCOTE_PROFILE_CONVERTER;
+        if (env)
+            return env;
+        // `__dirname` does not exist here: this package is `"type": "module"`, so the CJS globals are
+        // absent and referencing one throws a ReferenceError at runtime that typechecking cannot see.
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/ (or src/) -> ../../../tools/fingerprint-collect/convert_dataset.py
+        const guess = join(here, "..", "..", "..", "tools", "fingerprint-collect", "convert_dataset.py");
+        return existsSync(guess) ? guess : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=profilefetch.js.map

package/dist/profilefetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profilefetch.js","sourceRoot":"","sources":["../src/profilefetch.ts"],"names":[],"mappings":"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"}

package/dist/profileimport.d.ts

@@ -0,0 +1,22 @@
+import { type ProfileIndexEntry } from "./profilelib.js";
+/** Parse a clearcote-profile blob into an index entry. Returns null when the file is not one. */
+export declare function indexEntryFromProfile(id: string, profile: Record<string, unknown>): ProfileIndexEntry | null;
+export interface ImportResult {
+    index: ProfileIndexEntry[];
+    /** Files that were not usable, with the reason — surfaced rather than silently dropped, so a
+     *  half-converted directory is visible instead of quietly producing a thin pool. */
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+}
+/**
+ * Index every `*.json` in a directory.
+ *
+ * Reads each file once. For 10k profiles this is a few seconds and a lot of I/O, so callers
+ * should cache the result (`writeIndex`) rather than re-scanning per launch.
+ */
+export declare function importDirectory(dir: string): ImportResult;
+/** Load one profile from an imported directory, by the id `importDirectory` assigned it. */
+export declare function loadImportedProfile(dir: string, id: string): Record<string, unknown>;
+//# sourceMappingURL=profileimport.d.ts.map

package/dist/profileimport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileimport.d.ts","sourceRoot":"","sources":["../src/profileimport.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,iGAAiG;AACjG,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,iBAAiB,GAAG,IAAI,CAsD1B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B;wFACoF;IACpF,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAiCzD;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASpF"}

package/dist/profileimport.js

@@ -0,0 +1,125 @@
+// Generic profile importer: turn a DIRECTORY of clearcote-profile JSON into a selectable index.
+//
+// WE ARE AN IMPORTER, NOT A HOST. Clearcote ships no third-party fingerprints and redistributes
+// none. A source is just a folder of clearcote-profile JSON on the user's own machine, however
+// it got there:
+//
+//   * the open chrome-fingerprints dataset (Vinyzu), converted locally with
+//     tools/fingerprint-collect/convert_dataset.py — the dataset is fetched by the USER from the
+//     original repository, so nothing is re-published here and its terms are unaffected;
+//   * your own captures from tools/fingerprint-collect (collect.html / snippet.js);
+//   * the licensed clearcote profile service (see profilesource.ts);
+//   * any other producer that emits the same schema.
+//
+// Keeping the format as the ONLY contract is what makes this generic. There is no adapter per
+// vendor, no vendored data, and no decompressor for someone else's archive format baked into
+// three SDKs — a directory of JSON is something every source can produce and every SDK can read.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import { gpuVendorClass } from "./profilelib.js";
+/** Parse a clearcote-profile blob into an index entry. Returns null when the file is not one. */
+export function indexEntryFromProfile(id, profile) {
+    const nav = (profile.navigator ?? {});
+    const screen = (profile.screen ?? {});
+    const webgl = (profile.webgl ?? {});
+    const gl1 = (webgl.webgl1 ?? {});
+    const debug = (gl1.debug ?? {});
+    const meta = (profile.meta ?? {});
+    const ua = String(nav.user_agent ?? "");
+    const platform = String(nav.platform ?? "");
+    // UA-CH. Checked FIRST because it is the only source present on some real inputs: converted
+    // chrome-fingerprints records carry `uadata.platform` while leaving `user_agent` and
+    // `platform` null (the converter deliberately drops the browser version). Reading only the UA
+    // string silently skipped every one of those — 10,000 usable profiles classified as garbage.
+    const uadata = (nav.uadata ?? {});
+    const chPlatform = String(uadata.platform ?? (uadata.high_entropy?.platform ?? ""));
+    const chMobile = Boolean(uadata.mobile ?? uadata.high_entropy?.mobile);
+    let os;
+    if (chMobile || /android/i.test(chPlatform) || /android/i.test(ua))
+        os = "android";
+    else if (/windows|win/i.test(chPlatform) || /win/i.test(platform) || /Windows/i.test(ua))
+        os = "windows";
+    else if (/macos|mac/i.test(chPlatform) || /mac/i.test(platform) || /Mac OS X/i.test(ua))
+        os = "macos";
+    else if (/linux|chrome ?os|x11/i.test(chPlatform) || /linux|x11/i.test(platform) || /Linux/i.test(ua))
+        os = "linux";
+    else
+        return null; // unclassifiable: better to skip than to mislabel and mis-serve it
+    // Version is OPTIONAL by design. Hardware-only imports (e.g. converted chrome-fingerprints
+    // records) carry no browser version and inherit the engine's — see profilelib's browser_major.
+    const m = ua.match(/Chrome\/(\d+)/);
+    const browserMajor = m ? Number(m[1]) : null;
+    const renderer = debug.UNMASKED_RENDERER_WEBGL ?? null;
+    // The launch cost, measured the same way fingerprint.ts encodes it — so an entry that would
+    // blow the argv limit is excluded at selection time rather than failing at spawn.
+    const encodedSize = gzipSync(Buffer.from(JSON.stringify(profile)), { level: 9 }).toString("base64").length;
+    return {
+        id,
+        os_family: os,
+        browser_major: browserMajor,
+        gpu_vendor: gpuVendorClass(renderer),
+        renderer: renderer ?? undefined,
+        screen_width: screen.width,
+        screen_height: screen.height,
+        device_pixel_ratio: screen.device_pixel_ratio,
+        hardware_concurrency: profile.hardware_concurrency,
+        device_memory: profile.device_memory,
+        encoded_size: encodedSize,
+        captured_at: typeof meta.captured_at === "string" ? meta.captured_at : undefined,
+    };
+}
+/**
+ * Index every `*.json` in a directory.
+ *
+ * Reads each file once. For 10k profiles this is a few seconds and a lot of I/O, so callers
+ * should cache the result (`writeIndex`) rather than re-scanning per launch.
+ */
+export function importDirectory(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        throw new Error(`profile source is not a directory: ${dir}`);
+    }
+    const index = [];
+    const skipped = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const path = join(dir, f);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            skipped.push({ file: f, reason: `unreadable JSON: ${String(e).slice(0, 80)}` });
+            continue;
+        }
+        // A clearcote-profile always has navigator; without it this is some other kind of file.
+        // NOTE the check is on the SECTION, not on any field inside it — a converted
+        // chrome-fingerprints record has `navigator` with null user_agent/platform and is perfectly
+        // usable via uadata.
+        if (!parsed || typeof parsed !== "object" || !parsed.navigator) {
+            skipped.push({ file: f, reason: "not a clearcote-profile (no navigator)" });
+            continue;
+        }
+        const entry = indexEntryFromProfile(f.replace(/\.json$/, ""), parsed);
+        if (!entry) {
+            skipped.push({ file: f, reason: "could not classify os_family" });
+            continue;
+        }
+        index.push(entry);
+    }
+    return { index, skipped };
+}
+/** Load one profile from an imported directory, by the id `importDirectory` assigned it. */
+export function loadImportedProfile(dir, id) {
+    // The id is a filename stem this module produced, but it can reach here from a cached index,
+    // so treat it as untrusted: reject anything that could escape the source directory.
+    if (id.includes("/") || id.includes("\\") || id.includes("..")) {
+        throw new Error(`invalid profile id '${id}'`);
+    }
+    const path = join(dir, `${id}.json`);
+    if (!existsSync(path))
+        throw new Error(`profile '${id}' not found in ${dir}`);
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+//# sourceMappingURL=profileimport.js.map

package/dist/profileimport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileimport.js","sourceRoot":"","sources":["../src/profileimport.ts"],"names":[],"mappings":"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"}

package/dist/profilelib.d.ts

@@ -0,0 +1,100 @@
+/** One row of the profile index. Deliberately slim: selection never touches a blob until it has
+ *  picked a winner, so the index stays cheap to hold in memory and to ship. */
+export interface ProfileIndexEntry {
+    id: string;
+    os_family: "windows" | "macos" | "linux" | "android" | (string & {});
+    os_major?: string;
+    /**
+     * Chromium major of the capture, HARD-filtered against the engine's own major.
+     *
+     * `null`/absent means VERSION-AGNOSTIC and matches any engine. That is not a loophole — it is
+     * the correct description of a hardware-only profile. Imports from the chrome-fingerprints
+     * dataset deliberately drop the browser version (its records are Chrome ~114/115) and carry
+     * only version-independent identity: GPU, screen, fonts, voices, audio, CPU/memory, keyboard.
+     * Such a profile inherits the running engine's version, so it cannot contradict it.
+     *
+     * A profile that DOES pin a version and gets it wrong is a real contradiction — UA says 138
+     * while the engine behaves like 150 — which is why a mismatched number is still rejected.
+     */
+    browser_major?: number | null;
+    /** Coarse vendor class parsed from the renderer string: nvidia | amd | intel | apple | other. */
+    gpu_vendor: string;
+    /** Rough capability tier (0 = integrated, 1 = mainstream, 2 = high-end). */
+    gpu_tier?: number;
+    renderer?: string;
+    screen_width?: number;
+    screen_height?: number;
+    device_pixel_ratio?: number;
+    hardware_concurrency?: number;
+    device_memory?: number;
+    /** gzip+base64 length of the encoded profile — used to keep the launch under the argv limit. */
+    encoded_size?: number;
+    /** ISO date of capture; newer is mildly preferred. */
+    captured_at?: string;
+}
+/** What we know about the machine actually doing the rendering. */
+export interface HostFacts {
+    os_family: string;
+    browser_major: number;
+    gpu_vendor?: string;
+    gpu_tier?: number;
+    screen_width?: number;
+    screen_height?: number;
+    device_pixel_ratio?: number;
+    hardware_concurrency?: number;
+    device_memory?: number;
+}
+export type SelectMode = "best" | "rotate" | "random";
+export interface SelectOptions {
+    /** `"rotate"` (default) sticky-per-key; `"best"` always top-scoring; `"random"` fresh each call. */
+    mode?: SelectMode;
+    /** Stickiness key for `"rotate"` — an account id, proxy session, or profile name. */
+    key?: string;
+    /** Candidate pool the mode picks from. Wide enough to avoid herding, narrow enough to stay coherent. */
+    topN?: number;
+    /** Override the target OS (defaults to the host's). */
+    os?: string;
+    /** Hard ceiling on encoded size; entries above it cannot be launched on Windows. */
+    maxEncodedSize?: number;
+}
+/** Windows caps a process command line at 32767 chars. The profile rides on argv as
+ *  `--fingerprint-profile=<gzip+base64>`, and the rest of the switches need room too, so keep a
+ *  wide margin. Exceeding this is not a soft failure — Chromium refuses to spawn and Playwright
+ *  surfaces it as an opaque `spawn UNKNOWN`, which is why this is enforced at selection time. */
+export declare const DEFAULT_MAX_ENCODED = 24000;
+/** Coarse GPU vendor class from a renderer string (works for ANGLE and raw GL strings). */
+export declare function gpuVendorClass(renderer: string | undefined | null): string;
+/**
+ * Score a candidate against the host. Higher is better; the maximum is 1.
+ *
+ * Weights encode what a detector can actually catch, in descending order of how cheaply it can
+ * be caught:
+ *  - GPU class (0.45): string-vs-render mismatch is a single-call contradiction.
+ *  - Screen (0.25): a persona whose screen cannot contain the real window is the documented
+ *    "reliable block trigger"; a profile *larger* than the host display is the dangerous
+ *    direction, so it is penalised harder than a smaller one.
+ *  - DPR (0.10): interacts with screen and with CSS pixel math.
+ *  - Cores/memory (0.10): weakly checkable against measured worker parallelism.
+ *  - Freshness (0.10): a recent capture is likelier to match current Chrome behaviour.
+ */
+export declare function scoreProfile(entry: ProfileIndexEntry, host: HostFacts): number;
+/** Hard filters. A candidate failing any of these is not merely low-scoring — it is incoherent,
+ *  and no weight should be able to promote it back into the pool. */
+export declare function eligible(entry: ProfileIndexEntry, host: HostFacts, opts?: SelectOptions): boolean;
+export interface Selection {
+    entry: ProfileIndexEntry;
+    score: number;
+    /** How many candidates survived the hard filters — useful for spotting an over-narrow index. */
+    poolSize: number;
+    mode: SelectMode;
+}
+/**
+ * Pick a profile for this host.
+ *
+ * Throws when nothing is eligible rather than silently falling back to an incoherent profile —
+ * a wrong persona is worse than no persona, because it converts a clean browser into a
+ * contradictory one.
+ */
+export declare function selectProfile(index: ProfileIndexEntry[], host: HostFacts, opts?: SelectOptions): Selection;
+export declare function defaultStickyKey(): string;
+//# sourceMappingURL=profilelib.d.ts.map

package/dist/profilelib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profilelib.d.ts","sourceRoot":"","sources":["../src/profilelib.ts"],"names":[],"mappings":"AAyBA;+EAC+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iGAAiG;IACjG,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,oGAAoG;IACpG,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;iGAGiG;AACjG,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAIzC,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAU1E;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CA2C9E;AAED;qEACqE;AACrE,wBAAgB,QAAQ,CACtB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,aAAkB,GACvB,OAAO,CAWT;AAOD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,iBAAiB,EAAE,EAC1B,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,aAAkB,GACvB,SAAS,CAmCX;AAID,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC"}