jumpy-lion 0.1.6-beta.7 → 1.0.0-beta.0

package/dist/fingerprinting/ua-ch-brands.js

@@ -0,0 +1,174 @@
+/**
+ * UA-CH brand-list derivation - the GREASE token, its version, and the order
+ * of the three-entry brand list are all deterministic functions of the Chrome
+ * major version. This module is the single source of truth for that
+ * derivation; every surface that emits `sec-ch-ua` /
+ * `navigator.userAgentData.brands` (JS injection, CDP
+ * `Network.setUserAgentOverride` metadata, the native FingerprintConfig JSON,
+ * the bundled profile tables) must go through it.
+ *
+ * Why this matters: the GREASE entry is NOT arbitrary padding. Chromium
+ * (`components/embedder_support/user_agent_utils.cc`,
+ * `GetGreasedUserAgentBrandVersion` / `GenerateBrandVersionList`) derives the
+ * separators, the fake version and the list order from the major version:
+ *
+ *     brand   = 'Not' + chars[major % 11] + 'A' + chars[(major + 1) % 11] + 'Brand'
+ *     version = versions[major % 3]
+ *     order   = ORDERS[major % 6]   // permutation of [greasey, chromium, brand]
+ *
+ * So a profile's GREASE token is a fingerprint of the major it was harvested
+ * from. Carrying a Chrome 134 GREASE (`"Not:A-Brand";v="24"`) on a Chrome 147
+ * User-Agent yields a `sec-ch-ua` no Chromium has ever emitted - four lines of
+ * server-side code catch it. `search.shopping.naver.com` does exactly that and
+ * answers HTTP 418 with no challenge (issue #131).
+ *
+ * Corroboration for the derivation (real Chrome, on the wire): majors 116
+ * (`Not)A;Brand`/24), 128 (`Not;A=Brand`/24), 131 (`Not_A Brand`/24), 142
+ * (`Not_A Brand`/99, accepted by Naver). The order rule was verified against
+ * the 187 harvested `sec-ch-ua` strings bundled in `non-apify-profiles.json`
+ * (majors 140, 142, 143, 144, 145, 146 - every one matches `major % 6`).
+ */
+/** Separator pool - `greasey_chars` in `user_agent_utils.cc`. */
+const GREASEY_CHARS = [' ', '(', ':', '-', '.', '/', ')', ';', '=', '?', '_'];
+/** Fake-version pool - `greased_versions` in `user_agent_utils.cc`. */
+const GREASEY_VERSIONS = ['8', '99', '24'];
+/**
+ * The six permutations Chromium shuffles `[greasey, chromium, brand]` through,
+ * in the order they appear in `GenerateBrandVersionList`. `ORDERS[major % 6]`
+ * gives the target index of each of the three entries.
+ */
+const BRAND_ORDERS = [
+    [0, 1, 2],
+    [0, 2, 1],
+    [1, 0, 2],
+    [1, 2, 0],
+    [2, 0, 1],
+    [2, 1, 0],
+];
+/**
+ * Match the UA-CH GREASE brand token. Chrome rotates the label across releases
+ * ("Not_A Brand", "Not)A;Brand", "Not.A/Brand", …); the separators vary but the
+ * Not?A?Brand shape is stable. Anchored, so it only ever matches the GREASE
+ * entry and never a real brand.
+ */
+export function isGreaseBrand(brand) {
+    return /^Not.A.Brand$/i.test(brand);
+}
+/** The GREASE brand + version a real Chromium of this major emits. */
+export function greasedBrandForMajor(major) {
+    const brand = `Not${GREASEY_CHARS[major % GREASEY_CHARS.length]}A`
+        + `${GREASEY_CHARS[(major + 1) % GREASEY_CHARS.length]}Brand`;
+    return { brand, version: GREASEY_VERSIONS[major % GREASEY_VERSIONS.length] };
+}
+/**
+ * Rebuild a UA-CH brand list so it is byte-identical to what Chromium
+ * `version` emits: derived GREASE token, real brands re-stamped to `version`,
+ * and the triple permuted by `major % 6`.
+ *
+ * `version` selects the surface, from its own shape:
+ *   - `"147"`             → the `brands` surface; GREASE version is `"8"`
+ *   - `"147.0.7727.56"`   → the `fullVersionList` surface; GREASE version is `"8.0.0.0"`
+ *
+ * The profile's real brand *names* are preserved (a Chromium-only profile stays
+ * Chromium-only); only versions, the GREASE entry and the order are rewritten.
+ * A GREASE entry is added when the profile has none - a two-brand `sec-ch-ua`
+ * is refused by the same checks that reject a mismatched GREASE.
+ */
+export function alignBrandList(brands, version) {
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    if (!Number.isFinite(major)) {
+        return brands;
+    }
+    const isFullVersionSurface = version.includes('.');
+    const grease = greasedBrandForMajor(major);
+    const greaseEntry = {
+        brand: grease.brand,
+        version: isFullVersionSurface ? `${grease.version}.0.0.0` : grease.version,
+    };
+    const realBrands = brands
+        .filter(b => b?.brand && !isGreaseBrand(b.brand))
+        .map(b => ({ ...b, version }));
+    // Chromium's permutation is defined for exactly [greasey, chromium, brand].
+    // Anything else (Chromium-only profile, extra brands) keeps the profile's
+    // own order with the GREASE entry first rather than inventing a shuffle.
+    const chromium = realBrands.find(b => b.brand === 'Chromium');
+    const brand = realBrands.find(b => b.brand !== 'Chromium');
+    if (realBrands.length !== 2 || !chromium || !brand) {
+        return [greaseEntry, ...realBrands];
+    }
+    const order = BRAND_ORDERS[major % BRAND_ORDERS.length];
+    const ordered = [];
+    ordered[order[0]] = greaseEntry;
+    ordered[order[1]] = chromium;
+    ordered[order[2]] = brand;
+    return ordered;
+}
+/**
+ * The canonical brand list of a real Google Chrome build of `version` - what
+ * `sec-ch-ua` looks like when we have no profile brands to preserve.
+ */
+export function canonicalBrandList(version) {
+    return alignBrandList([{ brand: 'Chromium', version }, { brand: 'Google Chrome', version }], version);
+}
+/** Serialize a brand list into a `sec-ch-ua` / `sec-ch-ua-full-version-list` header value. */
+export function buildSecChUaHeader(brands) {
+    return brands.map(b => `"${b.brand}";v="${b.version}"`).join(', ');
+}
+/**
+ * Does this brand list carry the GREASE token its own major implies?
+ *
+ * Used as a pool-contamination gate: a real Chrome profile always agrees with
+ * the derivation, so a disagreement means the brand list was synthesized or
+ * re-stamped by something that did not know the rule (including older versions
+ * of this crawler). Returns a human-readable reason, or null when coherent.
+ */
+export function describeGreaseIncoherence(brands) {
+    if (brands.length === 0) {
+        return null;
+    }
+    const real = brands.filter(b => b?.brand && !isGreaseBrand(b.brand));
+    const anchor = real.find(b => b.brand === 'Chromium') ?? real[0];
+    const major = Number.parseInt(anchor?.version?.split('.')[0] ?? '', 10);
+    if (!Number.isFinite(major)) {
+        return null;
+    }
+    const expected = greasedBrandForMajor(major);
+    const actual = brands.find(b => b?.brand && isGreaseBrand(b.brand));
+    if (!actual) {
+        return `userAgentData.brands has no GREASE entry (real Chrome ${major} sends "${expected.brand}";v="${expected.version}")`;
+    }
+    if (actual.brand !== expected.brand || (actual.version ?? '').split('.')[0] !== expected.version) {
+        return `GREASE "${actual.brand}";v="${actual.version}" contradicts major ${major}`
+            + ` (Chromium derives "${expected.brand}";v="${expected.version}")`;
+    }
+    return null;
+}
+/**
+ * JS source for an expression that derives the brand list *inside the page*.
+ *
+ * The injected-script fallbacks (ua-ch, datadome-bypass) learn the Chrome
+ * version only at runtime, by parsing `navigator.userAgent`, so they cannot use
+ * the helpers above at build time. This keeps their derivation identical to
+ * ours instead of hardcoding a literal GREASE token that rots.
+ *
+ * @param majorExpr in-scope JS expression holding the major version
+ * @param versionExpr in-scope JS expression holding the version to stamp on the real brands
+ * @param style 'major' for the `brands` surface, 'full' for `fullVersionList`
+ */
+export function brandListScriptExpression(majorExpr, versionExpr, style) {
+    const chars = JSON.stringify(GREASEY_CHARS);
+    const versions = JSON.stringify(GREASEY_VERSIONS);
+    const orders = JSON.stringify(BRAND_ORDERS);
+    const greaseVersion = style === 'full' ? '_gv + ".0.0.0"' : '_gv';
+    return `(function () {
+        var _m = parseInt(${majorExpr}, 10);
+        var _c = ${chars}, _vs = ${versions}, _o = ${orders}[_m % 6];
+        var _gv = _vs[_m % 3];
+        var _out = [];
+        _out[_o[0]] = { brand: "Not" + _c[_m % 11] + "A" + _c[(_m + 1) % 11] + "Brand", version: ${greaseVersion} };
+        _out[_o[1]] = { brand: "Chromium", version: ${versionExpr} };
+        _out[_o[2]] = { brand: "Google Chrome", version: ${versionExpr} };
+        return _out;
+    })()`;
+}
+//# sourceMappingURL=ua-ch-brands.js.map

package/dist/fingerprinting/ua-ch-brands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ua-ch-brands.js","sourceRoot":"","sources":["../../src/fingerprinting/ua-ch-brands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,iEAAiE;AACjE,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAEvF,uEAAuE;AACvE,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AAEpD;;;;GAIG;AACH,MAAM,YAAY,GAAG;IACjB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CACH,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACvC,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAC9C,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG;UAC5D,GAAG,aAAa,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;IAClE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,CAAC,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsB,EAAE,OAAe;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,MAAM,oBAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAiB;QAC9B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO;KAC7E,CAAC;IAEF,MAAM,UAAU,GAAG,MAAM;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAEnC,4EAA4E;IAC5E,0EAA0E;IAC1E,yEAAyE;IACzE,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC;IAC3D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;QACjD,OAAO,CAAC,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;IAC1B,OAAO,OAAO,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAC9C,OAAO,cAAc,CACjB,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,EACrE,OAAO,CACV,CAAC;AACN,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACrD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAsB;IAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACxE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,IAAI,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,yDAAyD,KAAK,WAAW,QAAQ,CAAC,KAAK,QAAQ,QAAQ,CAAC,OAAO,IAAI,CAAC;IAC/H,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC/F,OAAO,WAAW,MAAM,CAAC,KAAK,QAAQ,MAAM,CAAC,OAAO,uBAAuB,KAAK,EAAE;cAC5E,uBAAuB,QAAQ,CAAC,KAAK,QAAQ,QAAQ,CAAC,OAAO,IAAI,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACrC,SAAiB,EACjB,WAAmB,EACnB,KAAuB;IAEvB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,OAAO;4BACiB,SAAS;mBAClB,KAAK,WAAW,QAAQ,UAAU,MAAM;;;mGAGwC,aAAa;sDAC1D,WAAW;2DACN,WAAW;;SAE7D,CAAC;AACV,CAAC"}

package/dist/index.d.ts

@@ -5,4 +5,9 @@ export { createCDPRouter } from "./crawler.js";
 export type { CDPRouter, CDPCrawlingContext, CDPCrawlerOptions, CDPLaunchContext, CDPRequestHandler } from "./crawler.js";
 export type { GotoOptions, SelectOptionOptions } from "./page.js";
 export { CdpPage };
+export { saveSession } from "./session/save.js";
+export { restoreSession, installSessionInjectionHook, buildStorageInjectionScript } from "./session/inject-hook.js";
+export { assertValidBundle, SCHEMA_VERSION } from "./session/types.js";
+export type { SessionBundle, SessionBundleBrowserProfile, SessionBundleFingerprintInput, SessionBundleProxyMeta, SessionBundleUserDataDir, SerializedCookie, StorageMap, LaunchSnapshot, } from "./session/types.js";
+export type { SaveSessionOptions } from "./session/save.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1H,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1H,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,CAAC;AAKnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACR,aAAa,EACb,2BAA2B,EAC3B,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,UAAU,EACV,cAAc,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -3,4 +3,10 @@ import CdpPage from "./page.js";
 export default CDPCrawler;
 export { createCDPRouter } from "./crawler.js";
 export { CdpPage };
+// Session bundle helpers - capture browser state into a single JSON blob and
+// rehydrate it into a second crawler for full profile / cookie / fingerprint
+// continuity. See .omc/plans/session-bundle-feature.md for design notes.
+export { saveSession } from "./session/save.js";
+export { restoreSession, installSessionInjectionHook, buildStorageInjectionScript } from "./session/inject-hook.js";
+export { assertValidBundle, SCHEMA_VERSION } from "./session/types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/input/dropdown-selector.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DropdownSelector - the deep module beside ElementTarget that owns the whole
+ * select/dropdown protocol: native `<select>` handling, custom-dropdown
+ * trigger detection, idempotent open (triggers TOGGLE, so blind clicks are
+ * racy), and option selection with bounded scrolling for virtualized lists
+ * and bounded polling for late-rendering options.
+ *
+ * Talks to the page only through the narrow {@link DropdownSelectorPort}
+ * (ElementTargetPort + waitForSelector + the loose visibility check), so the
+ * protocol is unit-testable with a scripted port. ElementTarget decides WHERE
+ * and WHEN for coordinate clicks; DropdownSelector orchestrates the
+ * select-specific sequence on top of the same port.
+ */
+import { type ElementTarget, type ElementTargetPort } from './element-target.js';
+export declare const SCROLL_ANIMATION_DELAY_MS = 200;
+export declare const OPTION_LOAD_DELAY_MS = 300;
+export declare const DROPDOWN_OPEN_DELAY_MS = 300;
+export declare const DEFAULT_SELECT_TIMEOUT_MS = 30000;
+export interface SelectOptionOptions {
+    /** Maximum wait time in milliseconds. Default: 30000 */
+    timeout?: number;
+    /** Bypass visibility and disabled checks. Default: false */
+    force?: boolean;
+    /** Wait for dropdown options to load after opening. Default: true */
+    waitForOptions?: boolean;
+    /** Maximum scroll attempts for virtualized dropdowns. Default: 10 */
+    maxScrollAttempts?: number;
+}
+/**
+ * The narrow set of page capabilities DropdownSelector consumes - everything
+ * ElementTarget needs, plus selector waiting, the LOOSE visibility check
+ * (display/visibility only), and a real coordinate click. The loose check is
+ * deliberate: a menu opened with a CSS opacity/transform fade-in reads
+ * opacity:0 for the first frames, which ElementTarget's strict check counts as
+ * "not visible".
+ */
+export interface DropdownSelectorPort extends ElementTargetPort {
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** display !== 'none' && visibility !== 'hidden' - nothing else. */
+    isLooselyVisible(selector: string): Promise<boolean>;
+    /**
+     * Dispatch a REAL trusted mouse click at viewport coordinates, through the
+     * CDP Input domain (the same path CdpPage.click uses).
+     */
+    clickAt(x: number, y: number): Promise<void>;
+}
+export declare class DropdownSelector {
+    private readonly port;
+    private readonly elements;
+    constructor(port: DropdownSelectorPort, elements: ElementTarget);
+    /**
+     * Selects one or more options from a select element or dropdown.
+     *
+     * Automatically handles both regular HTML select elements and custom dropdowns:
+     * - For <select> elements: Directly selects options within the select
+     * - For custom dropdowns: Automatically detects and clicks triggers to open dropdowns,
+     *   then selects the specified options with intelligent scrolling for virtualized lists
+     */
+    selectOption(dropdownSelector: string, optionSelector: string | string[], options?: SelectOptionOptions): Promise<void>;
+    /**
+     * Turn an in-page {@link ClickHandoff} into an actual click, and report
+     * whether the element ended up clicked.
+     *
+     * Preferred path: a measured rect -> a trusted CDP Input click at a point
+     * inside it (randomized under mouse humanization, exact centre otherwise, so
+     * deterministic tests are unaffected). The in-page synthetic fallback is
+     * already-done work and simply reports success.
+     */
+    private _completeHandoff;
+    /**
+     * Handles selection for regular HTML select elements
+     */
+    private _handleRegularSelect;
+    /**
+     * Handles selection for custom dropdown elements.
+     * Automatically detects and clicks triggers using multiple strategies:
+     * - Common trigger patterns ([aria-haspopup], .dropdown-trigger, etc.)
+     * - Previous sibling elements
+     * - ID pattern matching (menu → trigger)
+     */
+    private _handleCustomDropdown;
+    /**
+     * Selects a single option from a dropdown container.
+     * Handles virtualized lists with intelligent scrolling to find options that may not be initially visible.
+     */
+    private _selectOptionFromDropdown;
+}
+//# sourceMappingURL=dropdown-selector.d.ts.map

package/dist/input/dropdown-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropdown-selector.d.ts","sourceRoot":"","sources":["../../src/input/dropdown-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAyC,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAC7C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAChC,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAeD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC3D,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,oEAAoE;IACpE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAmCD,qBAAa,gBAAgB;IAErB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,IAAI,EAAE,oBAAoB,EAC1B,QAAQ,EAAE,aAAa;IAG5C;;;;;;;OAOG;IACG,YAAY,CACd,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,EACjC,OAAO,CAAC,EAAE,mBAAmB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAyDhB;;;;;;;;OAQG;YACW,gBAAgB;IAmB9B;;OAEG;YACW,oBAAoB;IA4ElC;;;;;;OAMG;YACW,qBAAqB;IA4HnC;;;OAGG;YACW,yBAAyB;CA8G1C"}