@reclaimprotocol/agent 0.1.10 → 0.1.11

package/src/old/tools/build.ts

@@ -3,7 +3,6 @@ import type { ReclaimOldClient } from '../client.ts'
 import type { ReclaimSdkClient } from '../sdk-client.ts'
 import { authenticateTool } from './authenticate.ts'
 import { getProviderInfoTool } from './get-provider-info.ts'
-import { getProviderVersionConfigTool } from './get-version-config.ts'
 import { getMeProvidersTool } from './me-providers.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
 import { sessionAnalyticsLogsTool } from './session-analytics-logs.ts'
@@ -27,7 +26,6 @@ export function buildOldBackendTools(
 		authenticateTool(client),
 		createVersionFromCaptureTool(client),
 		getMeProvidersTool(client),
-		getProviderVersionConfigTool(client),
 		getProviderInfoTool(sdkClient),
 		updateProviderMetadataTool(client),
 		sessionAnalyticsLogsTool(client),

package/src/old/tools/get-provider-info.ts

@@ -18,14 +18,17 @@ async function attempt(
 }
 
 /**
- * Read provider info from the PUBLIC production SDK backend
- * (`api.reclaimprotocol.org`) — the service the verification SDK/attestor
- * itself calls at runtime, NOT the old-devtools dashboard backend
- * (`get_provider_version_config`, `devapi.reclaimprotocol.org`, requires
- * auth). Both underlying reads are unauthenticated.
+ * The single provider-read tool for old-devtools mode. Reads from the PUBLIC
+ * production SDK backend (`api.reclaimprotocol.org`) — the service the
+ * verification SDK/attestor itself calls at runtime. No auth required, works
+ * for ANY provider.
  *
- * Fetches BOTH shapes in one call, since they're complementary:
- *   - `provider`: full provider + providerConfig, `customInjection` included.
+ * Fetches BOTH shapes in one call, since they're complementary and together
+ * cover everything a caller needs before re-publishing a new version:
+ *   - `provider`: the full provider + providerConfig — `customInjection`,
+ *     `userAgent`, `allowedInjectedRequestData`, `requestData`, everything.
+ *     This is what you read before create_provider_version_from_capture so
+ *     you can pass the whole config back (that tool carries nothing forward).
  *   - `configs`: the trimmed runtime recipe the attestor actually consumes —
  *     `customInjection` deliberately omitted, `isScriptRequestingClaim`
  *     computed instead.
@@ -38,15 +41,18 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'Read a PUBLISHED provider from the public production SDK backend ' +
 				'(api.reclaimprotocol.org — what the verification SDK/attestor ' +
 				'itself fetches at runtime), for ANY provider, no auth required. ' +
-				'Different from get_provider_version_config, which reads the old ' +
-				'devtools DASHBOARD backend and requires auth. \n\n' +
+				'This is the provider-read tool for old-devtools mode. \n\n' +
 				'Returns two complementary reads for the given version (latest ' +
-				'when `versionNumber` is omitted): `provider` (the full provider ' +
-				'+ providerConfig, including `customInjection`) and `configs` (the ' +
-				'trimmed recipe the attestor actually consumes — `customInjection` ' +
-				'is deliberately OMITTED there, replaced by a computed ' +
-				'`isScriptRequestingClaim` flag). One endpoint failing (e.g. an ' +
-				'invalid `versionNumber`) is reported under `errors` without ' +
+				'when `versionNumber` is omitted): `provider` (the FULL provider ' +
+				'+ providerConfig — `customInjection`, `userAgent`, ' +
+				'`allowedInjectedRequestData`, `requestData`, everything) and ' +
+				'`configs` (the trimmed recipe the attestor actually consumes — ' +
+				'`customInjection` is deliberately OMITTED there, replaced by a ' +
+				'computed `isScriptRequestingClaim` flag). Read `provider` here ' +
+				'BEFORE create_provider_version_from_capture so you can pass the ' +
+				'whole existing config back — that tool always creates a new ' +
+				'version and carries nothing forward. One endpoint failing (e.g. ' +
+				'an invalid `versionNumber`) is reported under `errors` without ' +
 				'hiding a result the other endpoint did return.',
 			inputSchema: {
 				type: 'object',

package/src/old/tools/publish.ts

@@ -12,7 +12,6 @@ import {
 	bumpPatchString,
 	extractVersions,
 	injectedRequestDataFrom,
-	type OldInjectedRequestData,
 	type OldProviderOpts,
 	providerToConfigBody,
 	providerToRegisterBody,
@@ -20,66 +19,6 @@ import {
 
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
 
-/** Fields with no partial-patch equivalent on this backend: a version always
- *  replaces the WHOLE `providerConfig`, so omitting one of these on
- *  add-version must carry forward the current value rather than publish it
- *  blank. `allowedInjectedRequestData` is handled alongside these (further
- *  down, inline) since it needs translation when freshly authored, unlike
- *  these — which pass through unchanged either way. */
-const PRESERVABLE_KEYS = [
-	'customInjection',
-	'userAgent',
-	'pageTitle',
-	'stepsToFollow',
-	'useIncognitoWebview',
-	'extensionConfig',
-] as const
-
-/** Pull `providerConfig` out of a `get_provider_version_config` /
- *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
-function extractProviderConfig(
-	resp: unknown,
-): Record<string, unknown> | undefined {
-	if(resp && typeof resp === 'object') {
-		const cfg = (resp as { providerConfig?: unknown }).providerConfig
-		if(cfg && typeof cfg === 'object') {
-			return cfg as Record<string, unknown>
-		}
-	}
-
-	return undefined
-}
-
-/** Prefer the caller's explicit value; otherwise fall back to `current`'s
- *  value (if any) and record `fieldName` as carried forward.
- *
- *  `current === null` is treated the SAME as `undefined` (nothing to carry),
- *  not as a real value to preserve. These are all optional fields with no
- *  Prisma default — a version where one was never set reads back as
- *  `null`, not a missing key, because Prisma normalizes an absent optional
- *  field to `null` on read. Carrying that `null` "forward" would falsely
- *  claim the field was preserved when really nothing was ever there — it
- *  most likely means an EARLIER version already lost it (e.g. published
- *  before this field had carry-forward support at all), not that this call
- *  is doing anything wrong. */
-function resolveField<T>(
-	explicit: T | undefined,
-	current: unknown,
-	fieldName: string,
-	carried: string[],
-): T | undefined {
-	if(explicit !== undefined) {
-		return explicit
-	}
-
-	if(current !== undefined && current !== null) {
-		carried.push(fieldName)
-		return current as T
-	}
-
-	return undefined
-}
-
 /**
  * The old backend lets you add a version only to a provider YOU own. A
  * `providerId` for a public provider (or anyone else's) comes back as
@@ -166,23 +105,19 @@ export function createVersionFromCaptureTool(
 				'For data gated behind login/navigation, pass `customInjection` — a ' +
 				'page-injection script (old-devtools\' name for the builder\'s ' +
 				'jsUserScripts) that drives the page to where the request fires. \n\n' +
-				'This backend has NO partial-patch endpoint — adding a version ' +
-				'always replaces the WHOLE providerConfig. When `providerId` is ' +
-				'set, any of `customInjection`, `userAgent`, `pageTitle`, ' +
-				'`allowedInjectedRequestData`, `stepsToFollow`, ' +
-				'`useIncognitoWebview`, `extensionConfig` that you OMIT is carried ' +
-				'forward unchanged from the currently-published version (so ' +
-				're-publishing requestData never wipes a working login script or ' +
-				'other config someone set via the dashboard). This can only carry ' +
-				'forward what the CURRENT version actually has — if an earlier ' +
-				'version already lost a field (e.g. published before this tool ' +
-				'carried it forward at all), there is nothing left to preserve and ' +
-				'the result legitimately comes back empty/null for that field; ' +
-				'that is not this call failing to carry it forward. Pass an ' +
-				'explicit value (`""`, `[]`, `false`, ...) to intentionally clear ' +
-				'one of them instead, or call get_provider_version_config FIRST ' +
-				'to see exactly what is live today, rather than assuming this ' +
-				'call recovered something that may already be gone. ' +
+				'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
+				'there is no partial-patch/edit endpoint, and this tool does NOT ' +
+				'read or carry anything forward from the previous version. Every ' +
+				'new version replaces the WHOLE providerConfig with exactly what ' +
+				'you pass in THIS call. Therefore any field you want present in the ' +
+				'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
+				'`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
+				'`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
+				'`provider`/`providers`). Anything you OMIT is published blank/' +
+				'default in the new version, NOT preserved. To change one field ' +
+				'while keeping the rest, first read the current version with ' +
+				'get_provider_info, then pass the full desired config (the existing ' +
+				'values plus your change) back into this call. ' +
 				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
 				'`extensionConfig` only take effect on add-version — the register ' +
 				'endpoint (no `providerId`) ignores them. \n\n' +
@@ -316,6 +251,28 @@ export function createVersionFromCaptureTool(
 									description:
 										'Fail validation if none match. Default true.',
 								},
+								templateParams: {
+									type: 'array',
+									items: { type: 'string' },
+									description:
+										'Names of `${var}` placeholders used in this ' +
+										'template\'s `responseMatches`/`responseRedactions` ' +
+										'that should be substituted at verify time from the ' +
+										'submitted proof\'s own witness params. Omit (or ' +
+										'leave empty) if the template has no such ' +
+										'placeholders.',
+								},
+								templateParamsMode: {
+									type: 'string',
+									enum: ['separate', 'merge'],
+									description:
+										'How multiple values for `templateParams` expand ' +
+										'into request specs. `separate` (default): one ' +
+										'independent spec per value, each matching its own ' +
+										'proof. `merge`: fold all values into ONE spec with ' +
+										'one match/redaction entry per value, matching a ' +
+										'single proof that bundles them all into one claim.',
+								},
 							},
 							required: ['url', 'method'],
 						},
@@ -356,25 +313,23 @@ export function createVersionFromCaptureTool(
 
 			const providers = hasMany ? args.providers! : [args.provider!]
 
-			const opts: OldProviderOpts = { initialUrl: args.initialUrl }
-			if(args.description !== undefined) {
-				opts.description = args.description
-			}
-
-			if(args.geoLocation !== undefined) {
-				opts.geoLocation = args.geoLocation
-			}
-
-			if(args.useProxy !== undefined) {
-				opts.useProxy = args.useProxy
-			}
-
-			if(args.providerType !== undefined) {
-				opts.providerType = args.providerType
-			}
-
-			if(args.customInjection !== undefined) {
-				opts.customInjection = args.customInjection
+			const opts: OldProviderOpts = {
+				initialUrl: args.initialUrl,
+				description: args.description,
+				geoLocation: args.geoLocation,
+				useProxy: args.useProxy,
+				providerType: args.providerType,
+				customInjection: args.customInjection,
+				userAgent: args.userAgent,
+				pageTitle: args.pageTitle,
+				stepsToFollow: args.stepsToFollow,
+				useIncognitoWebview: args.useIncognitoWebview,
+				extensionConfig: args.extensionConfig,
+				allowedInjectedRequestData: args.allowedInjectedRequestData
+					? injectedRequestDataFrom(
+						args.allowedInjectedRequestData,
+					)
+					: undefined
 			}
 
 			// Non-blocking advisory per request — never alters or blocks the
@@ -414,27 +369,15 @@ export function createVersionFromCaptureTool(
 					.filter((k) => args[k] !== undefined)
 				if(ignoredOnRegister.length) {
 					notes.push(
-						`${ignoredOnRegister.join(', ')} ${
-							ignoredOnRegister.length > 1 ? 'are' : 'is'
-						} ignored on register (no providerId) — the old backend only ` +
+						`${ignoredOnRegister.join(', ')} ` +
+						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
+						'ignored on register (no providerId) — the old backend only ' +
 						'reads them when adding a version. Publish once to create ' +
 						'the provider, then call this again WITH the returned ' +
 						'providerId to set them.',
 					)
 				}
 
-				if(args.userAgent !== undefined) {
-					opts.userAgent = args.userAgent
-				}
-
-				if(args.pageTitle !== undefined) {
-					opts.pageTitle = args.pageTitle
-				}
-
-				if(args.stepsToFollow !== undefined) {
-					opts.stepsToFollow = args.stepsToFollow
-				}
-
 				const body = providerToRegisterBody(providers, opts)
 				return withNotes(await client.registerProvider(body))
 			}
@@ -445,48 +388,12 @@ export function createVersionFromCaptureTool(
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId
 			try {
-				// This backend has no partial-patch endpoint — a version always
-				// replaces the WHOLE providerConfig. Anything the caller didn't
-				// pass at all is carried forward from the currently-published
-				// version instead of going out blank. Pass an explicit empty
-				// value ("", [], false) to intentionally clear one.
-				const needsCurrent = PRESERVABLE_KEYS.some((k) => args[k] === undefined)
-					|| args.allowedInjectedRequestData === undefined
-				const current = needsCurrent
-					? extractProviderConfig(await client.getProviderConfig(providerId))
-					: undefined
-
-				const carried: string[] = []
-				for(const key of PRESERVABLE_KEYS) {
-					const resolved = resolveField(args[key], current?.[key], key, carried)
-					if(resolved !== undefined) {
-						(opts as unknown as Record<string, unknown>)[key] = resolved
-					}
-				}
-
-				const freshInjected = args.allowedInjectedRequestData !== undefined
-					? injectedRequestDataFrom(args.allowedInjectedRequestData)
-					: undefined
-				const resolvedInjected = resolveField<OldInjectedRequestData[]>(
-					freshInjected,
-					current?.allowedInjectedRequestData,
-					'allowedInjectedRequestData',
-					carried,
-				)
-				if(resolvedInjected !== undefined) {
-					opts.allowedInjectedRequestData = resolvedInjected
-				}
-
-				if(carried.length) {
-					notes.push(
-						'Not passed, carried forward unchanged from the current ' +
-						`published version: ${carried.join(', ')}. Pass an explicit ` +
-						'value ("", [], false, ...) to override any of them, or ' +
-						'call get_provider_version_config first to see what is ' +
-						'live today.',
-					)
-				}
-
+				// By design this always POSTs a brand-new version and publishes
+				// EXACTLY the config assembled above — nothing is read back or
+				// carried forward. Any field the caller omitted is already absent
+				// from `opts` and will be blank/default in the new version. To
+				// preserve existing fields, the caller must have read them via
+				// get_provider_info and passed them back in.
 				if(args.customInjection !== undefined && opts.customInjection?.trim()) {
 					notes.push(
 						'customInjection will run in the verification client before ' +
@@ -495,6 +402,15 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
+				notes.push(
+					'A NEW version was created with only the fields passed in this ' +
+					'call — nothing was carried forward from the previous version. ' +
+					'If you intended to keep other fields (customInjection, ' +
+					'userAgent, allowedInjectedRequestData, ...), read the prior ' +
+					'version with get_provider_info and re-publish with them ' +
+					'included.',
+				)
+
 				const versionsResp = await client.listVersions(providerId)
 				const version = bumpPatchString(extractVersions(versionsResp))
 				const versionInfo =

package/src/provider/dom-xpath.ts

@@ -18,6 +18,104 @@ import '../proof/patch-domhandler.ts'
 const IDENT_ATTRS =
 	['name', 'property', 'itemprop', 'data-testid', 'rel', 'for']
 
+/** What an xPath candidate anchors on — used to weight its base stability. */
+type AnchorKind = 'ident-attr' | 'id' | 'class' | 'positional'
+
+/** One verified xPath option for the target element, tagged with what it
+ *  anchors on so it can be scored for FUTURE stability (see
+ *  {@link anchorStability}) rather than just "first that resolves". */
+interface Candidate {
+	xPath: string
+	kind: AnchorKind
+	/** The identifier the anchor keys on (an id / attr / class value); undefined
+	 *  for a purely positional path. */
+	token?: string
+	/** Ancestor distance from the value element (0 = the element itself or a
+	 *  direct-child anchor); larger = higher up. Tie-break nudge only. */
+	depth: number
+}
+
+/** Base weight by anchor kind: purpose-built test hooks and ids beat classes,
+ *  which beat a positional path. Modulated by {@link tokenQuality}. */
+const TYPE_WEIGHT: Record<AnchorKind, number> = {
+	'ident-attr': 0.95,
+	id: 0.9,
+	class: 0.6,
+	positional: 0.3,
+}
+
+const UUID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * How likely an identifier token is to survive a future render, by its SHAPE —
+ * framework-agnostic, so it catches generated ids/classes from any tool (this
+ * year's or next) without naming them. Returns `[0.02, 1]`.
+ *
+ * Volatile shapes (machine-generated): a `:` (React `useId` `:r1:`, Radix), a
+ * UUID, digit-heavy or trailing-digit tokens (`ember123`, `tab-2`), hex/hash
+ * runs (`css-1a2b3c`), or opaque wordless strings. Durable shapes (human
+ * authored): real word segments, kebab/snake of words (`settings-header`,
+ * `primary_email_select`).
+ */
+function tokenQuality(token: string): number {
+	const t = token.trim()
+	if(!t) {
+		return 0.3
+	}
+
+	// Kill signals — these tokens are (almost) always per-render generated.
+	if(t.includes(':') || UUID_RE.test(t)) {
+		return 0.05
+	}
+
+	let q = 1
+	const len = t.length
+	const digits = (t.match(/\d/g) ?? []).length
+	const digitRatio = digits / len
+	// A trailing digit run after letters is the classic generated-id tail.
+	if(/[A-Za-z][-_]?\d+$/.test(t)) {
+		q *= 0.3
+	}
+
+	if(digitRatio > 0.3) {
+		q *= 0.4
+	} else if(digitRatio > 0.15) {
+		q *= 0.7
+	}
+
+	// A pure hex/short-hash run (`1a2b3c`, `deadbeef`) — no semantic content.
+	if(/^[0-9a-f]{6,}$/i.test(t)) {
+		q *= 0.15
+	}
+
+	// A real word — an alpha run ≥3 that ITSELF contains a vowel — is the
+	// strongest durability signal; its absence means the token is opaque /
+	// hash-like (`css-1a2b3c`, `sc-bdfBwQ`). Checking per-segment matters: a
+	// stray vowel elsewhere in a hash must not count as "has a word".
+	const hasWord = (t.match(/[A-Za-z]+/g) ?? [])
+		.some((run) => run.length >= 3 && /[aeiou]/i.test(run))
+	if(!hasWord) {
+		q *= 0.3
+	}
+
+	if(len > 40) {
+		q *= 0.6
+	}
+
+	return Math.max(0.02, Math.min(1, q))
+}
+
+/** Stability score for a candidate: base weight for its kind × the shape
+ *  quality of its identifier, minus a small depth nudge so a nearer/shorter
+ *  anchor wins an otherwise-tie. Positional paths score on kind alone. */
+function anchorStability(c: Candidate): number {
+	const base = TYPE_WEIGHT[c.kind]
+	const quality = c.kind === 'positional' ? 1 : tokenQuality(c.token ?? '')
+	const depthNudge = 1 - Math.min(c.depth, 8) * 0.01
+	return base * quality * depthNudge
+}
+
 export interface DomAnchor {
 	xPath: string
 	/** Byte range of the element in the source html (parse5 source locations),
@@ -61,15 +159,25 @@ export function elementAnchor(
 		return undefined
 	}
 
-	for(const candidate of candidateXPaths(el)) {
-		if(matchesUniquely(doc, candidate, el)) {
-			// `[startIndex, endIndex)` is exactly the slice the attestor reveals for
-			// this xPath (its getNodeRange uses these same parse5 source locations).
-			return { xPath: candidate, start: startIndex, end: endIndex }
-		}
+	// Score EVERY candidate that provably resolves (first-match, uniquely) to the
+	// target, and take the most durable — not merely the first that resolves.
+	// Because each survivor already matches uniquely NOW, the choice only trades
+	// on FUTURE stability; it can never pick a wrong/non-resolving node.
+	const verified = [...candidateXPaths(el)]
+		.map((c, i) => ({ c, i }))
+		.filter(({ c }) => matchesUniquely(doc, c.xPath, el))
+	if(!verified.length) {
+		return undefined
 	}
 
-	return undefined
+	verified.sort((a, b) => {
+		return anchorStability(b.c) - anchorStability(a.c) ||
+			a.c.depth - b.c.depth ||
+			a.i - b.i
+	})
+	// `[startIndex, endIndex)` is exactly the slice the attestor reveals for this
+	// xPath (its getNodeRange uses these same parse5 source locations).
+	return { xPath: verified[0].c.xPath, start: startIndex, end: endIndex }
 }
 
 /** The tightest element that DIRECTLY holds a target. Prefers a COMPLETE-value
@@ -121,34 +229,29 @@ function smallestElement(els: Element[]): Element | undefined {
 		.at(0)
 }
 
-/** Candidate xPaths for `el`, best (most stable / shortest) first. */
-function* candidateXPaths(el: Element): Generator<string> {
+/** Every candidate xPath for `el`, each tagged with what it anchors on. The
+ *  caller verifies + scores them ({@link anchorStability}) rather than trusting
+ *  emission order, so the DURABILITY winner is chosen, not the first that
+ *  resolves. Order here is only the final tie-break. */
+function* candidateXPaths(el: Element): Generator<Candidate> {
 	const tag = el.name
 	const a = el.attribs ?? {}
 	if(a.id) {
-		yield `//${tag}[@id=${xpathLiteral(a.id)}]`
+		yield { xPath: `//${tag}[@id=${xpathLiteral(a.id)}]`, kind: 'id',
+			token: a.id, depth: 0 }
 	}
 
 	for(const name of IDENT_ATTRS) {
 		if(a[name]) {
-			yield `//${tag}[@${name}=${xpathLiteral(a[name])}]`
-		}
-	}
-
-	if(a.class) {
-		const distinctive = a.class
-			.split(/\s+/)
-			.filter(Boolean)
-			.sort((x, y) => y.length - x.length)[0]
-		if(distinctive) {
-			yield `//${tag}[contains(@class, ${xpathLiteral(distinctive)})]`
+			yield { xPath: `//${tag}[@${name}=${xpathLiteral(a[name])}]`,
+				kind: 'ident-attr', token: a[name], depth: 0 }
 		}
 	}
 
 	// A uniquely-identified DIRECT child pins the parent without a positional
-	// path (`//span[span[@id="labels"]]`). Self-verification (firstSelected)
-	// discards it when the child id/attr isn't unique — e.g. GitHub reuses
-	// `id="labels"` per email row — so it never silently matches the wrong node.
+	// path (`//span[span[@id="labels"]]`). Self-verification discards it when the
+	// child id/attr isn't unique — e.g. GitHub reuses `id="labels"` per email row
+	// — so it never silently matches the wrong node.
 	for(const child of el.children) {
 		if(!isTag(child)) {
 			continue
@@ -156,17 +259,114 @@ function* candidateXPaths(el: Element): Generator<string> {
 
 		const ca = child.attribs ?? {}
 		if(ca.id) {
-			yield `//${tag}[${child.name}[@id=${xpathLiteral(ca.id)}]]`
+			yield { xPath: `//${tag}[${child.name}[@id=${xpathLiteral(ca.id)}]]`,
+				kind: 'id', token: ca.id, depth: 0 }
 		}
 
 		for(const name of IDENT_ATTRS) {
 			if(ca[name]) {
-				yield `//${tag}[${child.name}[@${name}=${xpathLiteral(ca[name])}]]`
+				yield {
+					xPath: `//${tag}[${child.name}[@${name}=${xpathLiteral(ca[name])}]]`,
+					kind: 'ident-attr', token: ca[name], depth: 0,
+				}
+			}
+		}
+	}
+
+	// The value element's own distinctive class.
+	const distinctive = distinctiveClass(a.class)
+	if(distinctive) {
+		yield { xPath: `//${tag}[contains(@class, ${xpathLiteral(distinctive)})]`,
+			kind: 'class', token: distinctive, depth: 0 }
+	}
+
+	// Ancestor-anchored (id/attr, then class), descending positionally to `el`.
+	yield* ancestorAnchoredCandidates(el)
+
+	yield { xPath: absolutePath(el), kind: 'positional', depth: 99 }
+}
+
+/** The longest whitespace-delimited token of a class attribute (the most
+ *  distinctive one), or undefined when there's no class. */
+function distinctiveClass(cls: string | undefined): string | undefined {
+	return (cls ?? '')
+		.split(/\s+/)
+		.filter(Boolean)
+		.sort((x, y) => y.length - x.length)[0]
+}
+
+/** Positional path from `anc` (exclusive) down to `el` (inclusive), e.g.
+ *  `/ul[1]/li[3]/a[1]`; empty string when `anc` is not an ancestor of `el`. */
+function relativeSteps(anc: Element, el: Element): string {
+	const parts: string[] = []
+	let node: Node | null = el
+	while(node && isTag(node) && node !== anc) {
+		const tag = node.name
+		let index = 1
+		for(let sib = node.prev; sib; sib = sib.prev) {
+			if(isTag(sib) && sib.name === tag) {
+				index++
 			}
 		}
+
+		parts.unshift(`/${tag}[${index}]`)
+		node = node.parent
 	}
 
-	yield absolutePath(el)
+	return node === anc ? parts.join('') : ''
+}
+
+/** Ancestors of `el` (nearest first) with their depth, skipping
+ *  `html`/`body`/`head` (≈ the absolute path) and non-ancestors. Capped depth
+ *  keeps paths short. */
+function* anchorAncestors(el: Element): Generator<{
+	tag: string
+	attribs: Record<string, string>
+	rel: string
+	depth: number
+}> {
+	let depth = 1
+	for(
+		let anc: Node | null = el.parent;
+		anc && isTag(anc) && depth <= 10;
+		anc = anc.parent, depth++
+	) {
+		const tag = anc.name
+		if(tag === 'html' || tag === 'body' || tag === 'head') {
+			continue
+		}
+
+		const rel = relativeSteps(anc, el)
+		if(rel) {
+			yield { tag, attribs: anc.attribs ?? {}, rel, depth }
+		}
+	}
+}
+
+/** Ancestor-anchored candidates, descending positionally to `el`
+ *  (`//div[@id="nav"]/ul[1]/li[1]/a[1]`): an id / identifying-attr or a
+ *  distinctive-class anchor per ancestor, tagged with its kind + depth so the
+ *  scorer weighs a stable ancestor id above the value's own utility class. */
+function* ancestorAnchoredCandidates(el: Element): Generator<Candidate> {
+	for(const { tag, attribs, rel, depth } of anchorAncestors(el)) {
+		if(attribs.id) {
+			yield { xPath: `//${tag}[@id=${xpathLiteral(attribs.id)}]${rel}`,
+				kind: 'id', token: attribs.id, depth }
+		}
+
+		for(const name of IDENT_ATTRS) {
+			if(attribs[name]) {
+				const xp = `//${tag}[@${name}=${xpathLiteral(attribs[name])}]${rel}`
+				yield { xPath: xp, kind: 'ident-attr', token: attribs[name], depth }
+			}
+		}
+
+		const dc = distinctiveClass(attribs.class)
+		if(dc) {
+			yield { xPath: `//${tag}[contains(@class, ${xpathLiteral(dc)})]${rel}`,
+				kind: 'class', token: dc, depth }
+		}
+	}
 }
 
 /** Chrome "full XPath"-style absolute path: `/html[1]/body[1]/…/tag[n]`, where