browser-automation-skill 0.71.0

package/scripts/lib/common.sh

@@ -0,0 +1,262 @@
+# shellcheck shell=bash
+# scripts/lib/common.sh
+# Shared helpers for browser-automation-skill. Source this file from every
+# verb script and lib module. Mirrors mqtt-skill's lib/common.sh pattern.
+
+# Guard against double-sourcing.
+[ -n "${BROWSER_SKILL_COMMON_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_COMMON_LOADED=1
+
+# Restrictive umask for everything we create.
+umask 077
+
+# --- Exit code table (matches docs/superpowers/specs §5.1) ---
+# Consumed by every verb script via `die "${EXIT_USAGE_ERROR}"` etc.; shellcheck
+# can't see cross-file usage, so disable the unused-var warning for this block.
+# shellcheck disable=SC2034
+readonly EXIT_OK=0
+readonly EXIT_GENERIC_ERROR=1
+readonly EXIT_USAGE_ERROR=2
+readonly EXIT_EMPTY_RESULT=11
+readonly EXIT_PARTIAL_RESULT=12
+readonly EXIT_ASSERTION_FAILED=13
+readonly EXIT_PREFLIGHT_FAILED=20
+readonly EXIT_TOOL_MISSING=21
+readonly EXIT_SESSION_EXPIRED=22
+readonly EXIT_SITE_NOT_FOUND=23
+readonly EXIT_CREDENTIAL_AMBIGUOUS=24
+readonly EXIT_AUTH_INTERACTIVE_REQUIRED=25
+readonly EXIT_KEYCHAIN_LOCKED=26
+readonly EXIT_TTY_REQUIRED=27
+readonly EXIT_BLOCKLIST_REJECTED=28
+readonly EXIT_NETWORK_ERROR=30
+readonly EXIT_CAPTURE_WRITE_FAILED=31
+readonly EXIT_RETENTION_BLOCKED=32
+readonly EXIT_SCHEMA_MIGRATION_REQUIRED=33
+readonly EXIT_TOOL_UNSUPPORTED_OP=41
+readonly EXIT_TOOL_CRASHED=42
+readonly EXIT_TOOL_TIMEOUT=43
+
+# --- Tool adapter ABI version (single source of truth) ---
+# Bumping this is a [breaking] change. Every adapter's tool_metadata().abi_version
+# must equal this value; tests/lint.sh enforces it. See:
+# docs/superpowers/specs/2026-04-30-tool-adapter-extension-model-design.md §2.4
+readonly BROWSER_SKILL_TOOL_ABI=1
+
+# --- Logging ---
+# All logging goes to stderr. stdout is reserved for streaming JSON + summary.
+# Honors NO_COLOR=1 (https://no-color.org) and FORCE_COLOR=1.
+
+_browser_skill_color() {
+  if [ "${NO_COLOR:-0}" = "1" ]; then
+    printf ''
+    return
+  fi
+  if [ "${FORCE_COLOR:-0}" = "1" ] || [ -t 2 ]; then
+    printf '%s' "$1"
+    return
+  fi
+  printf ''
+}
+
+ok() {
+  local prefix
+  prefix="$(_browser_skill_color $'\033[0;32m')ok:$(_browser_skill_color $'\033[0m')"
+  printf '%s %s\n' "${prefix}" "$*" >&2
+}
+
+warn() {
+  local prefix
+  prefix="$(_browser_skill_color $'\033[0;33m')warn:$(_browser_skill_color $'\033[0m')"
+  printf '%s %s\n' "${prefix}" "$*" >&2
+}
+
+# die EXIT_CODE MESSAGE...
+# Prints to stderr in red, exits with the given code.
+die() {
+  local code="$1"
+  shift
+  local prefix
+  prefix="$(_browser_skill_color $'\033[0;31m')error:$(_browser_skill_color $'\033[0m')"
+  printf '%s %s\n' "${prefix}" "$*" >&2
+  exit "${code}"
+}
+
+# --- Path resolution ---
+# resolve_browser_skill_home echoes the canonical state-home path.
+# Resolution order:
+#   1. $BROWSER_SKILL_HOME (explicit override)
+#   2. Walk up from $PWD looking for .browser-skill/ (project-scoped mode)
+#   3. ~/.browser-skill/ (user-level fallback)
+resolve_browser_skill_home() {
+  if [ -n "${BROWSER_SKILL_HOME:-}" ]; then
+    printf '%s\n' "${BROWSER_SKILL_HOME}"
+    return 0
+  fi
+  local dir="${PWD}"
+  while [ "${dir}" != "/" ]; do
+    if [ -d "${dir}/.browser-skill" ]; then
+      printf '%s\n' "${dir}/.browser-skill"
+      return 0
+    fi
+    dir="$(dirname "${dir}")"
+  done
+  printf '%s\n' "${HOME}/.browser-skill"
+}
+
+# Convenience: export the resolved home + canonical subdirs once per invocation.
+# Verbs source common.sh and call this immediately.
+init_paths() {
+  BROWSER_SKILL_HOME="$(resolve_browser_skill_home)"
+  export BROWSER_SKILL_HOME
+  export SITES_DIR="${BROWSER_SKILL_HOME}/sites"
+  export SESSIONS_DIR="${BROWSER_SKILL_HOME}/sessions"
+  export CREDENTIALS_DIR="${BROWSER_SKILL_HOME}/credentials"
+  export CAPTURES_DIR="${BROWSER_SKILL_HOME}/captures"
+  export FLOWS_DIR="${BROWSER_SKILL_HOME}/flows"
+  export CURRENT_FILE="${BROWSER_SKILL_HOME}/current"
+  export CONFIG_FILE="${BROWSER_SKILL_HOME}/config.json"
+
+  # Adapter directory — single source of truth for "what adapters exist".
+  # Tools live one-file-per-adapter at $LIB_TOOL_DIR/<name>.sh; basename minus
+  # .sh is the canonical adapter name (enforced by tests/lint.sh §7.2).
+  local lib_dir
+  lib_dir="$(dirname "${BASH_SOURCE[0]}")"
+  export LIB_TOOL_DIR
+  LIB_TOOL_DIR="$(cd "${lib_dir}/tool" 2>/dev/null && pwd || printf '%s/tool' "${lib_dir}")"
+}
+
+# --- JSON summary writer ---
+# Usage: summary_json key=value key=value ...
+# Emits one valid JSON object per line on stdout. Uses jq for safe escaping —
+# never let bash interpolation construct JSON strings (quote bugs = leaks).
+# Numeric values (duration_ms, console_errors, etc.) stay as JSON numbers.
+summary_json() {
+  if [ "$#" -eq 0 ]; then
+    die "${EXIT_USAGE_ERROR}" "summary_json: no key=value pairs supplied"
+  fi
+
+  # JSON field names (e.g. `label`, `def`, `or`) can collide with jq's
+  # reserved keywords when used as VARIABLE names — `--arg label X` followed by
+  # `$label` in the filter triggers `syntax error, unexpected label`. Decouple
+  # the two name spaces: every jq variable is `$_v_<key>`, while the JSON field
+  # name stays `<key>`. Prefix is intentionally awkward to avoid colliding with
+  # any caller-supplied key like `v_url`.
+  local args=()
+  local pair key value
+  for pair in "$@"; do
+    case "${pair}" in
+      *=*)
+        key="${pair%%=*}"
+        value="${pair#*=}"
+        # Numeric? Pass as --argjson; else --arg (string). Reject leading-zero
+        # integers (e.g. capture_id "001") so they stay as strings — leading
+        # zeros are intentional padding, never numeric.
+        if [[ "${value}" =~ ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$ ]]; then
+          args+=(--argjson "_v_${key}" "${value}")
+        elif [ "${value}" = "true" ] || [ "${value}" = "false" ] || [ "${value}" = "null" ]; then
+          args+=(--argjson "_v_${key}" "${value}")
+        else
+          args+=(--arg "_v_${key}" "${value}")
+        fi
+        ;;
+      *)
+        die "${EXIT_USAGE_ERROR}" "summary_json: bad pair '${pair}' (expected key=value)"
+        ;;
+    esac
+  done
+
+  # Build the object dynamically: jq -n binds the prefixed variable names; the
+  # filter places each value under its caller-supplied JSON field name.
+  local jq_filter='. = {}'
+  for pair in "$@"; do
+    key="${pair%%=*}"
+    jq_filter="${jq_filter} | .${key} = \$_v_${key}"
+  done
+  jq -nc "${args[@]}" "${jq_filter}"
+}
+
+# --- Millisecond timestamp ---
+# now_ms echoes the current epoch time in milliseconds as a positive integer.
+# Verbs use this to compute duration_ms for their JSON summary.
+# Phase 12 part 2 perf: bash 5.0+ $EPOCHREALTIME first (fork-free); then GNU
+# date %3N (Linux); then BSD/macOS date second precision × 1000 (one fork,
+# still better than the prior python3 fork). The python3 fallback is removed
+# — bash 5.0 is universal on modern macOS/Linux + the skill's other bash-isms
+# already require Homebrew bash on macOS.
+now_ms() {
+  if [ -n "${EPOCHREALTIME:-}" ]; then
+    # EPOCHREALTIME = "<sec>.<microsec>". Slice to ms via parameter expansion.
+    local secs=${EPOCHREALTIME%.*}
+    local frac=${EPOCHREALTIME#*.}
+    printf '%s%s\n' "${secs}" "${frac:0:3}"
+    return 0
+  fi
+  local t
+  t="$(date +%s%3N 2>/dev/null)"
+  case "${t}" in
+    *N|'') printf '%s000\n' "$(date +%s)" ;;
+    *)     printf '%s\n' "${t}" ;;
+  esac
+}
+
+# now_iso echoes the current UTC time as RFC-3339 / ISO-8601, second precision,
+# trailing Z. Portable across GNU date (-u +%FT%TZ) and BSD date.
+now_iso() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+# file_mode PATH echoes the octal permission bits (e.g. "700", "0600") of PATH.
+# Portable across GNU stat (-c '%a') and BSD stat (-f '%Lp'). GNU is tried
+# first because GNU's `stat -f` does NOT fail on a regular file — it dumps
+# filesystem-status info instead, polluting stdout. So order matters:
+# GNU first; if -c is unrecognised (BSD), fall through to -f.
+file_mode() {
+  stat -c '%a' "$1" 2>/dev/null || stat -f '%Lp' "$1" 2>/dev/null
+}
+
+# --- Name safety ---
+# assert_safe_name NAME [FIELD_LABEL]
+# Refuses names that could escape a state dir or run outside the allowed
+# character set. Allowed chars: A-Z a-z 0-9 dash underscore. Empty rejected.
+# FIELD_LABEL (default "name") shows up in the error so callers can pass
+# "session-name", "default-session", etc. for clearer messages.
+assert_safe_name() {
+  local name="$1"
+  local field="${2:-name}"
+  if [[ ! "${name}" =~ ^[A-Za-z0-9_-]+$ ]]; then
+    die "${EXIT_USAGE_ERROR}" "${field} must match ^[A-Za-z0-9_-]+$ (got: ${name})"
+  fi
+}
+
+# --- Timeout wrapper ---
+# with_timeout SECONDS COMMAND ARGS...
+# Wraps `timeout` (GNU) or `gtimeout` (macOS coreutils) or a hand-rolled fallback.
+# On timeout: kills the child, returns EXIT_TOOL_TIMEOUT (43).
+# On success: returns the child's exit code.
+with_timeout() {
+  local secs="$1"
+  shift
+  local rc=0
+
+  if command -v timeout >/dev/null 2>&1; then
+    timeout --preserve-status -k 2 "${secs}" "$@" || rc=$?
+  elif command -v gtimeout >/dev/null 2>&1; then
+    gtimeout --preserve-status -k 2 "${secs}" "$@" || rc=$?
+  else
+    # Fallback: spawn child + watcher in subshell.
+    "$@" &
+    local child=$!
+    ( sleep "${secs}"; kill -TERM "${child}" 2>/dev/null; sleep 2; kill -KILL "${child}" 2>/dev/null ) &
+    local watcher=$!
+    wait "${child}" 2>/dev/null || rc=$?
+    kill "${watcher}" 2>/dev/null || true
+  fi
+
+  # 124 = GNU timeout's "timed out" code; 137 = SIGKILL; 143 = SIGTERM (fallback).
+  # Map any of these timeout signals to our 43.
+  if [ "${rc}" = "124" ] || [ "${rc}" = "137" ] || [ "${rc}" = "143" ]; then
+    return "${EXIT_TOOL_TIMEOUT}"
+  fi
+  return "${rc}"
+}

package/scripts/lib/credential.sh

@@ -0,0 +1,237 @@
+# scripts/lib/credential.sh
+# Credentials substrate: metadata I/O + backend dispatch.
+# Source from any verb / lib that needs credential CRUD.
+# Requires lib/common.sh sourced first (init_paths must have run).
+#
+# Two files per credential:
+#   ${CREDENTIALS_DIR}/<name>.json     — metadata (mode 0600, NEVER secrets)
+#   ${CREDENTIALS_DIR}/<name>.secret   — secret payload (backend-owned shape)
+#
+# Backend dispatch: metadata.backend ∈ {plaintext, keychain, libsecret}.
+# Each backend exposes the same 4-fn API (secret_set/get/delete/exists).
+# - plaintext  → scripts/lib/secret/plaintext.sh                  (this PR)
+# - keychain   → scripts/lib/secret/keychain.sh    (phase-05 part 2b)
+# - libsecret  → scripts/lib/secret/libsecret.sh   (phase-05 part 2c)
+#
+# AP-7: secret material flows via stdin pipes only — never argv. Helpers
+# credential_set_secret / credential_get_secret use stdin/stdout exclusively.
+# credential_load returns ONLY metadata; if you see a 'secret' key in its
+# output, that's a privacy regression — tests/credential.bats asserts this.
+
+[ -n "${BROWSER_SKILL_CREDENTIAL_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_CREDENTIAL_LOADED=1
+
+# --- Schema version (single source of truth for future migrations) ---
+# Bump this is a [schema] change; phase-10 introduces migrate-schema.
+readonly BROWSER_SKILL_CREDENTIAL_SCHEMA_VERSION=1
+
+# Bash array (not space-separated string) so iteration is IFS-independent.
+# Verb scripts set IFS=$'\n\t' which breaks word-splitting on space-separated
+# strings — using "${arr[@]}" sidesteps that.
+readonly _CREDENTIAL_REQUIRED_FIELDS=(schema_version name site account backend created_at)
+
+_credential_path() {
+  printf '%s/%s.json' "${CREDENTIALS_DIR}" "$1"
+}
+
+# --- Metadata CRUD ---
+
+# credential_exists NAME — 0 if metadata file present, 1 if not.
+credential_exists() {
+  [ -f "$(_credential_path "$1")" ]
+}
+
+# credential_save NAME META_JSON
+# Validates JSON + required fields. Refuses if NAME already exists (caller
+# must credential_delete first). Mode 0600. Atomically (tmp + mv).
+credential_save() {
+  local name="$1" meta_json="$2"
+  assert_safe_name "${name}" "credential-name"
+
+  if ! printf '%s' "${meta_json}" | jq -e . >/dev/null 2>&1; then
+    die "${EXIT_USAGE_ERROR}" "credential_save: metadata JSON is not valid"
+  fi
+
+  local field
+  for field in "${_CREDENTIAL_REQUIRED_FIELDS[@]}"; do
+    if ! printf '%s' "${meta_json}" | jq -e --arg f "${field}" 'has($f) and (.[$f] != null)' >/dev/null 2>&1; then
+      die "${EXIT_USAGE_ERROR}" "credential_save: metadata missing required field '${field}'"
+    fi
+  done
+
+  if credential_exists "${name}"; then
+    die "${EXIT_USAGE_ERROR}" "credential_save: ${name} already exists; call credential_delete first"
+  fi
+
+  mkdir -p "${CREDENTIALS_DIR}"
+  chmod 700 "${CREDENTIALS_DIR}"
+
+  local path tmp
+  path="$(_credential_path "${name}")"
+  tmp="${path}.tmp.$$"
+
+  ( umask 077; printf '%s\n' "${meta_json}" | jq . > "${tmp}" )
+  chmod 600 "${tmp}"
+  mv "${tmp}" "${path}"
+}
+
+# credential_load NAME → echoes metadata JSON (un-jq'd, exactly as on disk).
+# NEVER includes the secret payload.
+credential_load() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  local path
+  path="$(_credential_path "${name}")"
+  if [ ! -f "${path}" ]; then
+    die "${EXIT_SITE_NOT_FOUND}" "credential not found: ${name}"
+  fi
+  cat "${path}"
+}
+
+# credential_meta_load NAME — alias for credential_load. Provided for caller
+# clarity (some callers want to be explicit they're reading metadata).
+credential_meta_load() {
+  credential_load "$@"
+}
+
+# credential_list_names — sorted credential names, one per line. Excludes
+# .secret files. Empty (or missing) CREDENTIALS_DIR prints nothing.
+credential_list_names() {
+  if [ ! -d "${CREDENTIALS_DIR}" ]; then
+    return 0
+  fi
+  find "${CREDENTIALS_DIR}" -maxdepth 1 -type f -name '*.json' \
+    -exec basename {} .json \; 2>/dev/null | sort
+}
+
+# credential_delete NAME — removes metadata + secret (via backend). Idempotent.
+credential_delete() {
+  local name="$1"
+  assert_safe_name "${name}" "credential-name"
+  if credential_exists "${name}"; then
+    _credential_dispatch_backend "${name}" delete || true
+  else
+    # Try to clean up an orphan plaintext .secret with no metadata, just in case.
+    rm -f "${CREDENTIALS_DIR}/${name}.secret" 2>/dev/null || true
+  fi
+  rm -f "$(_credential_path "${name}")"
+}
+
+# --- Backend dispatch ---
+# credential_set_secret NAME — reads stdin, dispatches to backend's secret_set.
+# credential_get_secret NAME — dispatches to backend's secret_get → stdout.
+
+credential_set_secret() {
+  _credential_dispatch_backend "$1" set
+}
+
+credential_get_secret() {
+  _credential_dispatch_backend "$1" get
+}
+
+# Phase 5 part 4-ii: TOTP shared secret stored in the SAME backend as the
+# password but under a sibling slot named "<NAME>__totp". The double-
+# underscore suffix is allowed by assert_safe_name's regex
+# (^[A-Za-z0-9_-]+$) so backends can validate the slot name through their
+# normal path. Each cred's metadata still has only one entry; the backend
+# has two secret slots (password + TOTP). Edge: a user-facing cred named
+# `<X>__totp` would collide with `<X>`'s TOTP slot — `creds-add` rejects
+# names containing `__totp` to prevent this.
+
+credential_set_totp_secret() {
+  _credential_dispatch_backend_internal "$1__totp" set "$1"
+}
+
+credential_get_totp_secret() {
+  _credential_dispatch_backend_internal "$1__totp" get "$1"
+}
+
+# Internal: dispatch with a slot name SLOT_NAME but read backend from
+# CRED_NAME's metadata. Used by TOTP slot operations where the slot name
+# differs from the cred name but they share the backend.
+_credential_dispatch_backend_internal() {
+  local slot_name="$1" op="$2" cred_name="$3"
+  shift 3
+
+  local meta backend
+  meta="$(credential_load "${cred_name}")"
+  backend="$(printf '%s' "${meta}" | jq -r '.backend')"
+  _credential_dispatch_to "${backend}" "${op}" "${slot_name}" "$@"
+}
+
+# Internal: dispatch a secret op (set/get/delete/exists) to the backend
+# named by the credential's metadata.backend field. Backend lib is sourced
+# on-demand to keep the parent shell's namespace clean.
+_credential_dispatch_backend() {
+  local name="$1" op="$2"
+  shift 2
+
+  local meta backend
+  meta="$(credential_load "${name}")"
+  backend="$(printf '%s' "${meta}" | jq -r '.backend')"
+  _credential_dispatch_to "${backend}" "${op}" "${name}" "$@"
+}
+
+# _credential_dispatch_to BACKEND OP NAME [...args]
+# Like _credential_dispatch_backend but uses BACKEND directly (instead of
+# reading metadata.backend). Used by credential_migrate_to to write to the
+# new backend BEFORE updating metadata, so a failed new-write doesn't leave
+# the credential in an orphaned state.
+_credential_dispatch_to() {
+  local backend="$1" op="$2" name="$3"
+  shift 3
+
+  local lib_dir
+  lib_dir="$(dirname "${BASH_SOURCE[0]}")/secret"
+
+  case "${backend}" in
+    plaintext|keychain|libsecret)
+      # shellcheck source=/dev/null
+      source "${lib_dir}/${backend}.sh"
+      "secret_${op}" "${name}" "$@"
+      ;;
+    *)
+      die "${EXIT_USAGE_ERROR}" "credential ${name}: unknown backend '${backend}'"
+      ;;
+  esac
+}
+
+# credential_migrate_to NAME NEW_BACKEND
+# Move secret material from current backend to NEW_BACKEND, then update
+# metadata. Fail-safe ordering:
+#   1. Read secret from old backend
+#   2. Write secret to new backend (if this fails, original intact)
+#   3. Delete secret from old backend (failure → degraded but not fatal;
+#      verb script logs a warning, both backends transiently hold the secret)
+#   4. Update metadata.backend → new (atomic tmp+mv)
+# Refuses if new == old (no-op). Refuses unknown target backend.
+credential_migrate_to() {
+  local name="$1" new_backend="$2"
+  assert_safe_name "${name}" "credential-name"
+
+  case "${new_backend}" in
+    plaintext|keychain|libsecret) ;;
+    *) die "${EXIT_USAGE_ERROR}" "credential_migrate_to: unknown target backend '${new_backend}'" ;;
+  esac
+
+  local old_meta old_backend
+  old_meta="$(credential_load "${name}")"
+  old_backend="$(printf '%s' "${old_meta}" | jq -r '.backend')"
+
+  if [ "${old_backend}" = "${new_backend}" ]; then
+    die "${EXIT_USAGE_ERROR}" "credential ${name}: backend already '${new_backend}' (no-op refused)"
+  fi
+
+  local secret
+  secret="$(_credential_dispatch_to "${old_backend}" get "${name}")"
+  printf '%s' "${secret}" | _credential_dispatch_to "${new_backend}" set "${name}"
+  _credential_dispatch_to "${old_backend}" delete "${name}" || true
+
+  local new_meta path tmp
+  new_meta="$(printf '%s' "${old_meta}" | jq --arg b "${new_backend}" '.backend = $b')"
+  path="$(_credential_path "${name}")"
+  tmp="${path}.tmp.$$"
+  ( umask 077; printf '%s\n' "${new_meta}" | jq . > "${tmp}" )
+  chmod 600 "${tmp}"
+  mv "${tmp}" "${path}"
+}

package/scripts/lib/fingerprint-rescue.js

@@ -0,0 +1,123 @@
+// scripts/lib/fingerprint-rescue.js — Phase 13: weak-fingerprint selector rescue.
+//
+// Browser-side scoring algorithm. Runs inside the page via `browser-extract
+// --eval`. Receives a target fingerprint + threshold (inlined as constants by
+// scripts/lib/memory.sh::memory_fingerprint_rescue before eval) and returns
+// the synthesised selector for the highest-scoring DOM element above
+// threshold, or null on miss.
+//
+// Fingerprint shape (parsed bash-side from the cached CSS selector — "weak"
+// because we don't capture rich state at record-time):
+//   { tag:    "BUTTON" | "*",        // upper-case HTML tag, or wildcard
+//     classes: ["delete", "btn"],     // class tokens (.foo.bar in selector)
+//     attrs:  { id: "...", role: "..." }  // [name=value] selectors + #id
+//   }
+//
+// Scoring (algorithm cribbed from Scrapling adaptive parser, simplified for
+// CSS-selector inputs):
+//   score = 0.4 × tag_match
+//         + 0.4 × jaccard(classes_target, classes_candidate)
+//         + 0.2 × jaccard(attrs_target,   attrs_candidate)
+//
+// Synthesised selector priority (locked design choice):
+//   1. #id        when id is alphanumeric/hyphen and resolves uniquely
+//   2. [data-testid="…"]      preferred test-automation hook
+//   3. tag.class[.class…]     when this combination resolves uniquely
+//   4. nth-child path         absolute last-resort fallback
+//
+// Output (returned to bash via the eval channel):
+//   {"rescued_selector": "#submit-btn", "score": 0.82, "candidates_scanned": 1247}
+//   {"rescued_selector": null,          "score": 0.0,  "candidates_scanned": 1247}
+//
+// Phase 13. Best-effort — failure throws nothing; caller treats null as miss.
+
+(() => {
+  // __FP and __TH are constants prepended by memory_fingerprint_rescue.
+  // eslint-disable-next-line no-undef
+  const target = typeof __FP !== "undefined" ? __FP : { tag: "*", classes: [], attrs: {} };
+  // eslint-disable-next-line no-undef
+  const threshold = typeof __TH !== "undefined" ? __TH : 0.7;
+
+  function jaccard(a, b) {
+    if (a.length === 0 && b.length === 0) return 1.0;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    let intersect = 0;
+    setA.forEach((x) => { if (setB.has(x)) intersect++; });
+    const union = new Set([...setA, ...setB]).size;
+    return union === 0 ? 0 : intersect / union;
+  }
+
+  function score(el) {
+    const tagScore = target.tag === "*" || el.tagName === target.tag ? 1.0 : 0.0;
+    const candidateClasses = Array.from(el.classList);
+    const classScore = jaccard(target.classes, candidateClasses);
+    const targetAttrPairs = Object.entries(target.attrs).map(([k, v]) => `${k}=${v}`);
+    const candidateAttrPairs = Array.from(el.attributes).map((a) => `${a.name}=${a.value}`);
+    const attrScore = jaccard(targetAttrPairs, candidateAttrPairs);
+    return 0.4 * tagScore + 0.4 * classScore + 0.2 * attrScore;
+  }
+
+  function isSafeIdent(s) {
+    return typeof s === "string" && /^[A-Za-z][\w-]*$/.test(s);
+  }
+
+  function synthesise(el) {
+    // 1. #id (safe identifier + uniquely resolving)
+    if (el.id && isSafeIdent(el.id)) {
+      const sel = "#" + el.id;
+      try {
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      } catch (_) { /* invalid selector — fall through */ }
+    }
+    // 2. [data-testid="…"]
+    const testid = el.getAttribute("data-testid");
+    if (testid) {
+      const sel = '[data-testid="' + testid.replace(/"/g, '\\"') + '"]';
+      try {
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      } catch (_) { /* fall through */ }
+    }
+    // 3. tag.class[.class…] when uniquely resolving
+    if (el.classList.length > 0) {
+      const safeClasses = Array.from(el.classList).filter(isSafeIdent);
+      if (safeClasses.length > 0) {
+        const sel = el.tagName.toLowerCase() + "." + safeClasses.join(".");
+        try {
+          if (document.querySelectorAll(sel).length === 1) return sel;
+        } catch (_) { /* fall through */ }
+      }
+    }
+    // 4. nth-child path — climb to BODY
+    const path = [];
+    let cur = el;
+    while (cur && cur.tagName !== "HTML" && cur.parentElement) {
+      const parent = cur.parentElement;
+      const idx = Array.prototype.indexOf.call(parent.children, cur) + 1;
+      path.unshift(cur.tagName.toLowerCase() + ":nth-child(" + idx + ")");
+      if (parent.tagName === "BODY") break;
+      cur = parent;
+    }
+    return path.length > 0 ? path.join(" > ") : null;
+  }
+
+  let best = null;
+  let bestScore = 0;
+  let scanned = 0;
+  // Use a NodeList iterator — querySelectorAll('*') returns DOM order. Stable.
+  const all = document.querySelectorAll("*");
+  for (let i = 0; i < all.length; i++) {
+    scanned++;
+    const s = score(all[i]);
+    if (s > bestScore) {
+      bestScore = s;
+      best = all[i];
+    }
+  }
+  const rescued = best && bestScore >= threshold ? synthesise(best) : null;
+  return {
+    rescued_selector: rescued,
+    score: Math.round(bestScore * 100) / 100,
+    candidates_scanned: scanned,
+  };
+})();