wotann 0.5.0 → 0.5.39

package/dist/browser/adaptive-selectors.js

@@ -0,0 +1,317 @@
+/**
+ * Adaptive selectors — selectors that survive DOM redesigns by tracking
+ * element fingerprints and auto-relocating via fuzzy match.
+ *
+ * Modeled on D4Vinci/Scrapling's adaptive-selector pattern: a CSS / XPath
+ * selector usually breaks when a site redesigns. Adaptive selectors store
+ * enough metadata about the element (text, position-in-tree, sibling
+ * context, attributes) that the lookup can FALL BACK to fuzzy matching
+ * when the original selector misses.
+ *
+ * Pure data layer — accepts a typed `ElementShape` (a plain object), NOT
+ * a real DOM node. The driver (chrome-bridge / camoufox-backend / agentic-
+ * browser) is responsible for projecting real elements into ElementShape
+ * before calling buildFingerprint / score / findBestMatch. This keeps the
+ * module DOM-free, deterministic, and trivially unit-testable.
+ *
+ * QUALITY BARS
+ *   - QB#1 immutable: every fingerprint, selector, and result type is
+ *     `readonly`. mergeFingerprints returns a NEW fingerprint; it never
+ *     mutates either input.
+ *   - QB#3 honest tagged results: findBestMatch returns
+ *     { ok: true, element, score } | { ok: false, reason } so callers
+ *     can branch without throwing or guessing. score() returns a clamped
+ *     [0,1] number — never NaN, never out of range.
+ *   - QB#7 stateless: zero module-level mutable state. All inputs are
+ *     parameters; outputs are pure functions of inputs. Threshold and
+ *     scoring weights are exported `const`s callers can introspect.
+ *   - QB#11 sibling-site: this module ONLY scores plain shapes — it does
+ *     not touch DOM, CDP, or Playwright. The shape projection lives
+ *     centrally in chrome-bridge / camoufox-backend (see those files).
+ *   - QB#19 zombie-free: every exported symbol is referenced by tests
+ *     and intended for the agentic-browser caller. No dead instances.
+ */
+// ── Tunable scoring weights (exported so callers can introspect) ────────
+export const SCORE_WEIGHTS = {
+    tag: 0.2,
+    id: 0.3,
+    classOverlap: 0.2,
+    textJaccard: 0.2,
+    attrSetOverlap: 0.1,
+};
+/**
+ * Default minimum score for findBestMatch to consider a candidate a
+ * match. Below this, callers receive { ok: false, reason: "below_threshold" }.
+ */
+export const DEFAULT_MATCH_THRESHOLD = 0.6;
+/**
+ * Texts shorter than this token count are considered "low-information".
+ * Their Jaccard similarity is dampened so a short shared word like
+ * "OK" doesn't anchor a match between unrelated buttons.
+ */
+const LOW_INFO_TOKEN_THRESHOLD = 3;
+const TEXT_TOPK_TOKENS = 50;
+// ── Pure helpers ─────────────────────────────────────────────────────────
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+function truncate(s, max) {
+    if (typeof s !== "string")
+        return "";
+    return s.length <= max ? s : s.slice(0, max);
+}
+function tokenize(text) {
+    if (!text)
+        return [];
+    // Lowercase, split on non-word, drop empties. Stable across redesigns.
+    return text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length > 0);
+}
+function topKTokens(text, k) {
+    const all = tokenize(text);
+    if (all.length <= k)
+        return all;
+    return all.slice(0, k);
+}
+function jaccard(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    if (setA.size === 0 || setB.size === 0)
+        return 0;
+    let intersect = 0;
+    for (const v of setA) {
+        if (setB.has(v))
+            intersect++;
+    }
+    const union = setA.size + setB.size - intersect;
+    if (union === 0)
+        return 0;
+    return intersect / union;
+}
+function attrSetKeys(attrs) {
+    // Compare key=value pairs as a single token so both presence AND value
+    // matter (data-testid="login" vs data-testid="signup" must not match).
+    const keys = [];
+    for (const [k, v] of Object.entries(attrs)) {
+        keys.push(`${k}=${v}`);
+    }
+    return keys;
+}
+function summarizeSiblings(prev, next) {
+    const p = truncate((prev ?? "").trim(), 80);
+    const n = truncate((next ?? "").trim(), 80);
+    return `prev<<${p}>>next<<${n}>>`;
+}
+function freezeStringArray(arr) {
+    return Object.freeze([...arr]);
+}
+function freezeAttrs(attrs) {
+    // Sort keys for deterministic equality between rebuilt fingerprints.
+    const sorted = {};
+    for (const k of Object.keys(attrs).sort()) {
+        const v = attrs[k];
+        if (typeof v === "string")
+            sorted[k] = v;
+    }
+    return Object.freeze(sorted);
+}
+// ── Public API ───────────────────────────────────────────────────────────
+/**
+ * Build a fingerprint from an element shape. Pure. Input is not
+ * mutated; output is fully frozen.
+ */
+export function buildFingerprint(element) {
+    const fp = {
+        tag: (element.tag || "").toLowerCase(),
+        ...(element.id ? { id: element.id } : {}),
+        classNames: freezeStringArray(element.classNames ?? []),
+        textContent: truncate((element.textContent ?? "").trim(), 200),
+        attrs: freezeAttrs(element.attrs ?? {}),
+        siblingContext: summarizeSiblings(element.prevSiblingText, element.nextSiblingText),
+        cssPath: element.cssPath ?? "",
+        xpath: element.xpath ?? "",
+    };
+    return Object.freeze(fp);
+}
+/**
+ * Wrap a selector + element into a persistable AdaptiveSelector with
+ * a built-in ordered list of fallback strategies. The strategies are
+ * NAMES of approaches, not executable code — the caller's lookup
+ * engine picks each one up and executes it against a live DOM.
+ */
+export function buildAdaptiveSelector(args) {
+    const fingerprint = buildFingerprint(args.element);
+    const strategies = freezeStringArray([
+        "by-text",
+        "by-attr-set",
+        "by-sibling-context",
+        "by-class-overlap",
+        "by-xpath",
+    ]);
+    return Object.freeze({
+        originalSelector: args.selector,
+        fingerprint,
+        fallbackStrategies: strategies,
+    });
+}
+/**
+ * Score a candidate element against a fingerprint. Returns a number
+ * in [0,1]. Pure — never throws, never returns NaN.
+ *
+ * Components (weights from SCORE_WEIGHTS):
+ *   - tag match           : 1 if exact, else 0
+ *   - id match            : 1 if both have an id and they match, else
+ *                           0. If neither has an id, the weight is
+ *                           redistributed proportionally to other
+ *                           components (we don't penalize id-less elts).
+ *   - class overlap       : Jaccard of class name sets
+ *   - text Jaccard        : Jaccard of top-K tokens, dampened when
+ *                           total token count is below LOW_INFO threshold
+ *   - attr set overlap    : Jaccard of "k=v" pairs
+ */
+export function score(candidate, fingerprint) {
+    if (!candidate || !fingerprint)
+        return 0;
+    const cTag = (candidate.tag || "").toLowerCase();
+    const fTag = fingerprint.tag.toLowerCase();
+    const tagScore = cTag === fTag && cTag.length > 0 ? 1 : 0;
+    // ID handling: if EITHER side lacks an id, redistribute the id weight
+    // across the remaining components so we don't punish id-less DOMs.
+    const bothHaveId = !!candidate.id && !!fingerprint.id;
+    let idContribution = 0;
+    let weightTag = SCORE_WEIGHTS.tag;
+    let weightClass = SCORE_WEIGHTS.classOverlap;
+    let weightText = SCORE_WEIGHTS.textJaccard;
+    let weightAttr = SCORE_WEIGHTS.attrSetOverlap;
+    if (bothHaveId) {
+        idContribution = candidate.id === fingerprint.id ? SCORE_WEIGHTS.id : 0;
+    }
+    else {
+        // Redistribute id weight across the other four components evenly.
+        const slice = SCORE_WEIGHTS.id / 4;
+        weightTag += slice;
+        weightClass += slice;
+        weightText += slice;
+        weightAttr += slice;
+    }
+    const classScore = jaccard(candidate.classNames ?? [], fingerprint.classNames ?? []);
+    const candTokensAll = tokenize(candidate.textContent ?? "");
+    const fpTokensAll = tokenize(fingerprint.textContent ?? "");
+    const candTokens = topKTokens(candidate.textContent ?? "", TEXT_TOPK_TOKENS);
+    const fpTokens = topKTokens(fingerprint.textContent ?? "", TEXT_TOPK_TOKENS);
+    let textScore = jaccard(candTokens, fpTokens);
+    // Dampen low-information matches: if either side has very few tokens
+    // and they're not exact, halve the contribution so a stray "OK" or
+    // "Submit" doesn't anchor unrelated buttons.
+    if (candTokensAll.length < LOW_INFO_TOKEN_THRESHOLD ||
+        fpTokensAll.length < LOW_INFO_TOKEN_THRESHOLD) {
+        if (textScore < 1)
+            textScore *= 0.5;
+    }
+    const attrScore = jaccard(attrSetKeys(candidate.attrs ?? {}), attrSetKeys(fingerprint.attrs ?? {}));
+    const total = tagScore * weightTag +
+        idContribution +
+        classScore * weightClass +
+        textScore * weightText +
+        attrScore * weightAttr;
+    return clamp01(total);
+}
+/**
+ * Pick the highest-scoring candidate >= threshold (default 0.6).
+ * Returns a tagged union — never throws.
+ */
+export function findBestMatch(candidates, fingerprint, options = {}) {
+    if (!fingerprint || !fingerprint.tag) {
+        return Object.freeze({ ok: false, reason: "invalid_fingerprint" });
+    }
+    if (!candidates || candidates.length === 0) {
+        return Object.freeze({ ok: false, reason: "no_candidates" });
+    }
+    const threshold = typeof options.threshold === "number" && Number.isFinite(options.threshold)
+        ? clamp01(options.threshold)
+        : DEFAULT_MATCH_THRESHOLD;
+    let bestIdx = -1;
+    let bestScore = -1;
+    for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        if (!c)
+            continue;
+        const s = score(c, fingerprint);
+        if (s > bestScore) {
+            bestScore = s;
+            bestIdx = i;
+        }
+    }
+    if (bestIdx < 0) {
+        return Object.freeze({ ok: false, reason: "no_candidates" });
+    }
+    if (bestScore < threshold) {
+        return Object.freeze({
+            ok: false,
+            reason: "below_threshold",
+            bestScore,
+        });
+    }
+    const matched = candidates[bestIdx];
+    if (!matched) {
+        return Object.freeze({ ok: false, reason: "no_candidates" });
+    }
+    return Object.freeze({
+        ok: true,
+        element: matched,
+        score: bestScore,
+    });
+}
+// ── Adaptive update ──────────────────────────────────────────────────────
+/**
+ * Merge a previously stored fingerprint with a freshly observed one.
+ * Used to "drift" the stored snapshot as a site evolves so we don't
+ * keep re-matching against stale state.
+ *
+ * Strategy:
+ *   - Tag: prefer prior (tags rarely change; if they do the selector is
+ *     probably wrong anyway)
+ *   - id: prefer observed (ids that come and go are rare; observed wins)
+ *   - classNames: union (a redesign typically ADDS classes; rarely
+ *     removes the originals immediately)
+ *   - textContent: prefer observed (text is the most volatile)
+ *   - attrs: per-key prefer observed; keep prior keys not present in
+ *     observed (so transient render gaps don't drop a stable data-id)
+ *   - siblingContext / cssPath / xpath: prefer observed
+ *
+ * Pure: neither input is mutated.
+ */
+export function mergeFingerprints(prior, observed) {
+    const mergedClasses = freezeStringArray(Array.from(new Set([...(prior.classNames ?? []), ...(observed.classNames ?? [])])));
+    const mergedAttrs = {};
+    for (const [k, v] of Object.entries(prior.attrs ?? {})) {
+        mergedAttrs[k] = v;
+    }
+    for (const [k, v] of Object.entries(observed.attrs ?? {})) {
+        mergedAttrs[k] = v;
+    }
+    const observedHasId = !!observed.id;
+    const idValue = observedHasId ? observed.id : prior.id;
+    const merged = {
+        tag: prior.tag || observed.tag,
+        ...(idValue ? { id: idValue } : {}),
+        classNames: mergedClasses,
+        textContent: truncate(observed.textContent || prior.textContent || "", 200),
+        attrs: freezeAttrs(mergedAttrs),
+        siblingContext: observed.siblingContext || prior.siblingContext,
+        cssPath: observed.cssPath || prior.cssPath,
+        xpath: observed.xpath || prior.xpath,
+    };
+    return Object.freeze(merged);
+}
+//# sourceMappingURL=adaptive-selectors.js.map

package/dist/browser/adaptive-selectors.js.map

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

package/dist/browser/humanize-input.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Behavioral input humanization — defeats FingerprintJS / Cloudflare bot
+ * detection by generating mouse paths, typing cadences, and scroll
+ * profiles indistinguishable from human behavior.
+ *
+ * Ported from CloakBrowser research. WOTANN already uses Camoufox for
+ * browser-side stealth (fingerprint masking, WebGL spoof, canvas noise),
+ * but Camoufox does NOT humanize INPUT — straight-line mouse paths and
+ * uniform keypress intervals are the most reliable bot tells.
+ *
+ * This module emits driver-agnostic event streams:
+ *   - readonly Point[]       — mouse path with cubic-Bézier curvature
+ *   - readonly TypingEvent[] — press/backspace stream with bigram-aware
+ *                              cadence + occasional typo+correction
+ *   - readonly ScrollEvent[] — accel/cruise/decel scroll profile
+ *
+ * The runner (chrome-bridge, atomic-actions, etc.) consumes these as
+ * timed sequences and dispatches via CDP / Playwright.
+ *
+ * QUALITY BARS
+ *   - QB#1  immutable: all inputs `readonly`, all outputs `Object.freeze`d
+ *   - QB#6  honest output: deterministic with seed; no Math.random leakage
+ *   - QB#7  per-call state: mulberry32 PRNG is local to each call
+ *   - QB#11 sibling-site scan: only this module owns input humanization
+ *   - QB#13 env guard: zero `process.env` reads
+ *
+ * NO deps: mulberry32 PRNG is ~10 LOC inline.
+ */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+}
+export interface MouseHumanizeOptions {
+    readonly startMs?: number;
+    readonly minDurationMs?: number;
+    readonly maxDurationMs?: number;
+    readonly seed?: number;
+    readonly overshoot?: boolean;
+}
+export interface TypingHumanizeOptions {
+    readonly text: string;
+    readonly startMs?: number;
+    readonly meanIntervalMs?: number;
+    readonly typoProbability?: number;
+    readonly seed?: number;
+}
+export interface TypingEvent {
+    readonly type: "press" | "backspace";
+    readonly key: string;
+    readonly t: number;
+}
+export interface ScrollHumanizeOptions {
+    readonly fromY: number;
+    readonly toY: number;
+    readonly startMs?: number;
+    readonly seed?: number;
+}
+export interface ScrollEvent {
+    readonly y: number;
+    readonly t: number;
+}
+export declare function humanizeMousePath(from: Point, to: Point, opts?: MouseHumanizeOptions): readonly Point[];
+export declare function humanizeTyping(opts: TypingHumanizeOptions): readonly TypingEvent[];
+/**
+ * Human scroll profiles have three distinct phases:
+ *   1. Acceleration — short ramp-up from rest (~15-25% of duration)
+ *   2. Cruise       — sustained peak velocity through the middle
+ *   3. Deceleration — soft landing on the target Y (~25-35% of duration)
+ *
+ * Bot scroll detection looks for either constant-velocity (instant jump)
+ * or linear ramp (uniformly accelerated). This profile uses a trapezoid
+ * with rounded corners that matches real wheel/trackpad behavior.
+ */
+export declare function humanizeScroll(opts: ScrollHumanizeOptions): readonly ScrollEvent[];
+//# sourceMappingURL=humanize-input.d.ts.map

package/dist/browser/humanize-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanize-input.d.ts","sourceRoot":"","sources":["../../src/browser/humanize-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAyDD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,KAAK,EACT,IAAI,GAAE,oBAAyB,GAC9B,SAAS,KAAK,EAAE,CAoFlB;AAoHD,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,SAAS,WAAW,EAAE,CA4ClF;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,SAAS,WAAW,EAAE,CA+ElF"}