my-frontend-observer 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,37 @@
 # Changelog
 
-## Unreleased
+## 0.2.0 - 2026-08-11
+
+Stable Semantic Targets and Region Identity.
+
+- Canonical `{name, locators}` target model with a stable observer-owned
+  target identity, distinct from both the browser locator that resolves a
+  target and any source-code symbol. The existing `--target id=selector`
+  CSS shorthand remains fully supported and normalizes into this model
+  unchanged.
+- Six frozen, real-Chromium-resolved locator kinds per target, evaluated in
+  configured order with fallback on no match, immediate stop (no fallback)
+  on ambiguous or unevaluable results: `role` (+ optional exact accessible
+  name), `id`, `data-attribute`, `semantic-element`, `css`, and `text`
+  (exact match only).
+- Explicit missing/ambiguous/unavailable resolution reporting, and hidden
+  (present-but-not-visible) target evidence, for every locator kind.
+- Bounded semantic-region evidence per resolved target: accessibility
+  state (`disabled`/`expanded`/`checked`/`selected`/`pressed`/`current`,
+  with an explicit `false` always distinguishable from "not applicable"),
+  derived landmark identity, and configured-target-only DOM containment.
+- Proven stable request identity: the same target configuration produces
+  the same request identity across repeated observations; changing a
+  target's locator strategy changes the request identity without changing
+  its stable name; a target's actual runtime disappearance is
+  distinguishable from a configuration change.
+- New `--targets-file <json-file>` CLI input for structured semantic target
+  configuration, mutually exclusive with `--target`.
+- Observation schema `1.1.0`.
+- Cross-platform packed-candidate validation: one hash-verified npm
+  candidate tarball proven on Windows, Linux, and macOS, covering both the
+  legacy `--target` CSS shorthand and the structured `--targets-file`
+  semantic-target path.
 
 ## 0.1.0 - 2026-08-11
 

package/README.md

@@ -6,11 +6,12 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.1.0`, Runtime Observation Foundation, is the current published release:
-`my-frontend-observer observe` launches a real, sandboxed Chromium browser,
-enforces a loopback-only safety policy, captures a viewport screenshot plus
-bounded page/target evidence, and persists it as one portable
-`manifest.json` + `screenshot.png` artifact.
+`v0.2.0`, Stable Semantic Targets and Region Identity, is the current
+published release: `my-frontend-observer observe` launches a real,
+sandboxed Chromium browser, enforces a loopback-only safety policy,
+captures a viewport screenshot plus bounded page/target evidence, and
+persists it as one portable `manifest.json` + `screenshot.png` artifact
+(observation schema `1.1.0`).
 
 Install:
 
@@ -44,6 +45,14 @@ This prints a concise result (`Observation:`/`State:`/`Artifact:`/`Targets:`/
 `Diagnostics:`) and exits `0` on a successfully persisted observation. See
 [docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference.
 
+`--target <id=css-selector>` remains the simple CSS shorthand. A second,
+structured `--targets-file <json-file>` input mode ships as part of this
+release - supporting a role and accessible name, a stable `id`, a `data-*`
+attribute, a semantic landmark element, exact text, or an ordered fallback
+between several of those. See "Structured semantic targets" in
+[docs/COMMANDS.md](docs/COMMANDS.md#structured-semantic-targets-targets-file)
+for the exact JSON format.
+
 Validation:
 
 ```powershell
@@ -61,8 +70,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1 is released,
-  v0.2 is next.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1 and v0.2 are
+  released, v0.3 is next.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/browser/evidenceCapture.d.ts

@@ -15,5 +15,21 @@ export interface TargetEvidenceCaptureResult {
     targetEvidence: Record<string, TargetEvidenceRecord>;
     diagnostics: Diagnostic[];
 }
-/** Observes every explicitly configured Batch 1 target from the same live page, honoring the 0/1/many cardinality contract. */
+/**
+ * Observes every explicitly configured target from the same live page,
+ * honoring the frozen ordered-locator resolution contract: 0 matches tries
+ * the next locator; exactly 1 match selects and stops; more than 1 match is
+ * ambiguous and stops (never falls through); an unevaluable locator is
+ * unavailable and stops (never falls through). Ambiguity never triggers
+ * fallback.
+ *
+ * Batch 3 restructures this into three phases over one resolved set: (1)
+ * resolve every configured target exactly once, keeping a live
+ * `{locator, handle}` for each match; (2) compute bounded pairwise DOM
+ * containment among only the resolved configured targets, reusing those
+ * same handles (never re-resolving, never a second/independent resolution
+ * algorithm); (3) measure every resolved target and assemble its evidence,
+ * attaching the phase-2 containment result. Every handle is disposed once,
+ * after all three phases, regardless of outcome.
+ */
 export declare function captureTargetEvidence(page: Page, targets: readonly NamedTarget[]): Promise<TargetEvidenceCaptureResult>;

package/dist/browser/evidenceCapture.js

@@ -1,4 +1,5 @@
 import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { TARGET_LANDMARK_ROLES } from '../domain/schema.js';
 function diagnostic(code, message, targetName) {
     const base = { code, severity: DIAGNOSTIC_SEVERITY[code], message };
     return targetName === undefined ? base : { ...base, targetName };
@@ -63,7 +64,12 @@ function parseAriaSnapshotFirstLine(snapshot) {
     const firstLine = snapshot.split('\n')[0]?.trim();
     if (!firstLine)
         return undefined;
-    const match = /^-\s+([A-Za-z][\w-]*)\s*(?:"([^"]*)")?:?$/.exec(firstLine);
+    // No trailing `$` anchor: an element with no accessible name still produces
+    // a role line with unquoted trailing content (e.g. `- banner: Site Header`,
+    // verified empirically against real Chromium), which must still yield the
+    // role even though there is no quoted, genuinely-computed accessible name
+    // to report - trailing unquoted text is never treated as a name.
+    const match = /^-\s+([A-Za-z][\w-]*)\s*(?:"([^"]*)")?:?/.exec(firstLine);
     if (!match)
         return undefined;
     const role = match[1];
@@ -72,130 +78,399 @@ function parseAriaSnapshotFirstLine(snapshot) {
         return undefined;
     return name !== undefined && name.length > 0 ? { role, name } : { role };
 }
-function missingTargetRecord() {
-    const reason = 'target selector matched no element';
-    return {
-        resolution: { state: 'available', source: 'derived', value: { selectionMethod: 'css-selector', selectionStatus: 'not-found' }, derivedFrom: ['selector-query'] },
-        tag: unavailableField(reason),
-        geometry: unavailableField(reason),
-        style: unavailableField(reason),
-        layout: unavailableField(reason),
-        visibility: unavailableField(reason),
-        semantics: unavailableField(reason),
+/** Builds the shared unresolved-target evidence record (not-found/ambiguous/unavailable) with the full ordered attempt history and no selected locator. Containment is reported separately by the caller (its own "self unresolved" reason differs from the measurement-unavailable reason used here). */
+function unresolvedTargetRecord(selectionStatus, attempts, reason, containment) {
+    const resolution = {
+        selectionMethod: 'ordered-locators',
+        selectionStatus,
+        usedFallback: false,
+        confidence: 'none',
+        attempts,
     };
-}
-function ambiguousTargetRecord(matchCount) {
-    const reason = `target selector matched ${matchCount} elements; expected exactly one`;
     return {
-        resolution: { state: 'available', source: 'derived', value: { selectionMethod: 'css-selector', selectionStatus: 'ambiguous' }, derivedFrom: ['selector-query'] },
+        resolution: { state: 'available', source: 'derived', value: resolution, derivedFrom: ['locator-attempts'] },
         tag: unavailableField(reason),
         geometry: unavailableField(reason),
         style: unavailableField(reason),
         layout: unavailableField(reason),
         visibility: unavailableField(reason),
         semantics: unavailableField(reason),
+        semanticState: unavailableField(reason),
+        landmark: unavailableField(reason),
+        containment,
     };
 }
+const TARGET_LANDMARK_ROLE_SET = new Set(TARGET_LANDMARK_ROLES);
 /**
- * Captures the v0.1 minimum target evidence for one resolved (single-match)
- * target element, from the same live page/readiness state as the page
- * evidence and screenshot. Role/name come from Playwright's real
- * accessibility tree (`page.accessibility.snapshot`), not a hand-rolled
- * approximation; when the browser cannot supply them reliably for this
- * element, they are reported `unavailable` rather than guessed.
+ * Reads the resolved element's own native form-control properties and
+ * explicit `aria-*` attributes: bounded, target-local browser/ARIA state.
+ * `ariaSnapshot()`'s bracket annotations were verified empirically (real
+ * Chromium via the installed Playwright 1.62.1) to appear only for
+ * true/mixed values - they cannot distinguish an explicit false from "not
+ * applicable to this element", and they never expose `aria-current` at all.
+ * This direct property/attribute read is the investigated, honest
+ * alternative for exactly those two gaps; it still reads only real
+ * browser-native/ARIA semantics (never class names, CSS, text content, or
+ * source ownership). A key is present in the result only when the browser
+ * exposes that state as applicable to this specific element.
  */
-async function captureResolvedTargetRecord(page, selector) {
-    const handle = await page.$(selector);
-    if (!handle)
-        return missingTargetRecord();
-    try {
-        const raw = await handle.evaluate((el) => {
-            const rect = el.getBoundingClientRect();
-            const computed = getComputedStyle(el);
-            return {
-                tag: el.tagName.toLowerCase(),
-                geometry: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, right: rect.right, bottom: rect.bottom },
-                style: { display: computed.display, position: computed.position, overflowX: computed.overflowX, overflowY: computed.overflowY },
-                layout: {
-                    scrollWidth: el.scrollWidth,
-                    scrollHeight: el.scrollHeight,
-                    clientWidth: el.clientWidth,
-                    clientHeight: el.clientHeight,
-                    scrollTop: el.scrollTop,
-                    scrollLeft: el.scrollLeft,
-                },
-                computedVisibility: computed.visibility,
-            };
-        });
-        const visible = raw.style.display !== 'none' && raw.computedVisibility !== 'hidden' && raw.geometry.width > 0 && raw.geometry.height > 0;
-        let semantics;
-        try {
-            const snapshot = await page.locator(selector).ariaSnapshot();
-            const parsed = parseAriaSnapshotFirstLine(snapshot);
-            semantics = parsed ? computedField(parsed) : unavailableField('no distinct accessible role/name is exposed for this target');
+async function captureSemanticState(handle) {
+    return handle.evaluate((el) => {
+        const result = {};
+        const ariaDisabled = el.getAttribute('aria-disabled');
+        const nativeDisabled = 'disabled' in el ? Boolean(el.disabled) : false;
+        if (nativeDisabled || ariaDisabled !== null)
+            result.disabled = nativeDisabled || ariaDisabled === 'true';
+        const ariaExpanded = el.getAttribute('aria-expanded');
+        if (ariaExpanded !== null)
+            result.expanded = ariaExpanded === 'true';
+        const ariaChecked = el.getAttribute('aria-checked');
+        const isNativeCheckable = el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio');
+        if (ariaChecked !== null) {
+            result.checked = ariaChecked === 'mixed' ? 'mixed' : ariaChecked === 'true';
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            semantics = unavailableField(`accessibility snapshot failed: ${message}`);
+        else if (isNativeCheckable) {
+            result.checked = el.indeterminate ? 'mixed' : el.checked;
         }
+        const ariaSelected = el.getAttribute('aria-selected');
+        if (ariaSelected !== null)
+            result.selected = ariaSelected === 'true';
+        const ariaPressed = el.getAttribute('aria-pressed');
+        if (ariaPressed !== null)
+            result.pressed = ariaPressed === 'mixed' ? 'mixed' : ariaPressed === 'true';
+        const ariaCurrent = el.getAttribute('aria-current');
+        if (ariaCurrent !== null && ariaCurrent !== 'false' && ariaCurrent.length > 0) {
+            result.current = ariaCurrent === 'true' ? true : ariaCurrent;
+        }
+        return result;
+    });
+}
+/** Wraps the raw captured state: an empty object means no supported state applies to this target ("not-applicable"), never an unexplained empty available value. */
+function semanticStateEvidence(raw) {
+    if (Object.keys(raw).length === 0) {
+        return { state: 'not-applicable', reason: 'no supported semantic state is exposed for this target' };
+    }
+    return { state: 'available', source: 'computed-browser', value: raw };
+}
+/** Derives landmark identity from the already-captured browser-exposed role only - never from locator kind or HTML tag (Section 15). */
+function landmarkEvidence(role) {
+    if (role === undefined)
+        return unavailableField('no distinct accessible role is exposed for this target');
+    if (TARGET_LANDMARK_ROLE_SET.has(role)) {
+        return { state: 'available', source: 'derived', value: role, derivedFrom: ['semantics.role'] };
+    }
+    return { state: 'not-applicable', reason: `role "${role}" is not a recognized landmark role` };
+}
+/**
+ * Wraps a computed configured-target-only containment result into the
+ * persisted EvidenceField. `selfUnresolvedReason` covers the case where the
+ * current target itself never resolved (Section 18: containment is
+ * `unavailable`, not partial, when there is no resolved element to check
+ * containment for). A computed result with any `unresolvedTargetIds` is
+ * `partial` (already-proven relationships are preserved, never dropped);
+ * with none, it is `available`.
+ */
+function containmentEvidence(computed, selfUnresolvedReason) {
+    if (selfUnresolvedReason !== undefined)
+        return { state: 'unavailable', reason: selfUnresolvedReason };
+    if (!computed)
+        return { state: 'unavailable', reason: 'containment could not be computed' };
+    if (computed.unresolvedTargetIds.length > 0) {
+        return {
+            state: 'partial',
+            source: 'browser',
+            value: computed,
+            reason: `containment could not be evaluated against: ${computed.unresolvedTargetIds.join(', ')}`,
+        };
+    }
+    return { state: 'available', source: 'browser', value: computed };
+}
+/**
+ * Captures the full target evidence for one resolved (single-match) target
+ * element, from the same live page/readiness state as the page evidence and
+ * screenshot: tag/geometry/style/layout/visibility (v0.1), role/name
+ * semantics (v0.1, via `ariaSnapshot()`), and semantic state/landmark
+ * (Batch 3). Takes an already-resolved `{ locator, handle }` pair - not a
+ * raw CSS selector, and never re-resolves - so every locator kind converges
+ * on this one measurement path and containment (computed once by the caller
+ * across every resolved target before this runs) is simply passed through.
+ */
+async function captureResolvedTargetRecord(target, handle, attempts, selectedLocatorIndex, containment) {
+    const raw = await handle.evaluate((el) => {
+        const rect = el.getBoundingClientRect();
+        const computed = getComputedStyle(el);
         return {
-            resolution: {
-                state: 'available',
-                source: 'derived',
-                value: { selectionMethod: 'css-selector', selectionStatus: 'matched' },
-                derivedFrom: ['selector-query'],
+            tag: el.tagName.toLowerCase(),
+            geometry: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, right: rect.right, bottom: rect.bottom },
+            style: { display: computed.display, position: computed.position, overflowX: computed.overflowX, overflowY: computed.overflowY },
+            layout: {
+                scrollWidth: el.scrollWidth,
+                scrollHeight: el.scrollHeight,
+                clientWidth: el.clientWidth,
+                clientHeight: el.clientHeight,
+                scrollTop: el.scrollTop,
+                scrollLeft: el.scrollLeft,
             },
+            computedVisibility: computed.visibility,
+        };
+    });
+    const visible = raw.style.display !== 'none' && raw.computedVisibility !== 'hidden' && raw.geometry.width > 0 && raw.geometry.height > 0;
+    let semantics;
+    let resolvedRole;
+    try {
+        const snapshot = await target.ariaSnapshot();
+        const parsed = parseAriaSnapshotFirstLine(snapshot);
+        semantics = parsed ? computedField(parsed) : unavailableField('no distinct accessible role/name is exposed for this target');
+        resolvedRole = parsed?.role;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        semantics = unavailableField(`accessibility snapshot failed: ${message}`);
+    }
+    let semanticState;
+    try {
+        semanticState = semanticStateEvidence(await captureSemanticState(handle));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        semanticState = unavailableField(`semantic-state evaluation failed: ${message}`);
+    }
+    const resolution = {
+        selectionMethod: 'ordered-locators',
+        selectionStatus: 'matched',
+        selectedLocatorKind: attempts[selectedLocatorIndex]?.locatorKind ?? 'css',
+        selectedLocatorIndex,
+        usedFallback: selectedLocatorIndex > 0,
+        confidence: 'exact',
+        attempts,
+    };
+    return {
+        record: {
+            resolution: { state: 'available', source: 'derived', value: resolution, derivedFrom: ['locator-attempts'] },
             tag: browserField(raw.tag),
             geometry: browserField(raw.geometry),
             style: computedField(raw.style),
             layout: browserField(raw.layout),
             visibility: derivedField({ visible }, ['style.display', 'computed-visibility', 'geometry.width', 'geometry.height']),
             semantics,
-        };
+            semanticState,
+            landmark: landmarkEvidence(resolvedRole),
+            containment,
+        },
+        visible,
+    };
+}
+/**
+ * A CSS quoted-string literal for an attribute selector value (`[attr="..."]`).
+ * Only backslash and double-quote need escaping inside a CSS quoted string;
+ * this keeps the configured id/data-attribute value literal - it is never
+ * reinterpreted as selector syntax (e.g. a value containing `#`, `.`, `[`,
+ * or `"` still matches exactly, it cannot escape the attribute-value
+ * position it was placed in).
+ */
+function cssAttributeValueLiteral(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Maps one frozen v0.2 TargetLocator to the Playwright `Locator` that
+ * resolves it - the single point where locator kind becomes a real browser
+ * query. `role`/`text` use Playwright's own semantic locators (real
+ * accessibility-tree/text resolution, not a hand-rolled approximation);
+ * `id`/`data-attribute` use an exact CSS attribute-equals selector (never
+ * `#id`/bare-value syntax, so the configured value can never be
+ * reinterpreted as selector syntax); `semantic-element` uses a plain tag
+ * selector from the Batch 1 frozen tag set; `css` is unchanged v0.1
+ * behavior. Every kind converges on the same Playwright `Locator` type, so
+ * cardinality/measurement downstream never branches on locator kind again.
+ */
+function buildPlaywrightLocator(page, locator) {
+    switch (locator.kind) {
+        case 'css':
+            return page.locator(locator.selector);
+        case 'id':
+            return page.locator(`[id=${cssAttributeValueLiteral(locator.value)}]`);
+        case 'data-attribute':
+            return page.locator(`[${locator.attribute}=${cssAttributeValueLiteral(locator.value)}]`);
+        case 'semantic-element':
+            return page.locator(locator.tag);
+        case 'role':
+            return page.getByRole(locator.role, locator.name === undefined ? undefined : { name: locator.name, exact: true });
+        case 'text':
+            return page.getByText(locator.text, { exact: true });
     }
-    finally {
-        await handle.dispose();
+}
+/**
+ * Evaluates one locator against the live page: builds its real Playwright
+ * `Locator` and measures cardinality via `.count()` (no waiting, no
+ * `.first()`/`.nth(0)` shortcut that would silently resolve an ambiguous
+ * match). A locator that cannot be constructed or counted reliably is
+ * `unavailable`, never silently treated as zero matches.
+ */
+async function evaluateLocatorAttempt(page, locator) {
+    try {
+        const playwrightLocator = buildPlaywrightLocator(page, locator);
+        const matchCount = await playwrightLocator.count();
+        if (matchCount === 0)
+            return { playwrightLocator, outcome: { status: 'not-found', matchCount: 0 } };
+        if (matchCount > 1)
+            return { playwrightLocator, outcome: { status: 'ambiguous', matchCount } };
+        return { playwrightLocator, outcome: { status: 'matched', matchCount: 1 } };
+    }
+    catch {
+        return { playwrightLocator: undefined, outcome: { status: 'unavailable' } };
     }
 }
-/** Observes every explicitly configured Batch 1 target from the same live page, honoring the 0/1/many cardinality contract. */
+/**
+ * Observes every explicitly configured target from the same live page,
+ * honoring the frozen ordered-locator resolution contract: 0 matches tries
+ * the next locator; exactly 1 match selects and stops; more than 1 match is
+ * ambiguous and stops (never falls through); an unevaluable locator is
+ * unavailable and stops (never falls through). Ambiguity never triggers
+ * fallback.
+ *
+ * Batch 3 restructures this into three phases over one resolved set: (1)
+ * resolve every configured target exactly once, keeping a live
+ * `{locator, handle}` for each match; (2) compute bounded pairwise DOM
+ * containment among only the resolved configured targets, reusing those
+ * same handles (never re-resolving, never a second/independent resolution
+ * algorithm); (3) measure every resolved target and assemble its evidence,
+ * attaching the phase-2 containment result. Every handle is disposed once,
+ * after all three phases, regardless of outcome.
+ */
 export async function captureTargetEvidence(page, targets) {
     const targetEvidence = {};
     const diagnostics = [];
+    const infos = [];
+    // Phase 1: resolve every configured target exactly once.
     for (const target of targets) {
-        const matchCount = await page.evaluate((selector) => document.querySelectorAll(selector).length, target.selector);
-        if (matchCount === 0) {
-            targetEvidence[target.name] = missingTargetRecord();
-            diagnostics.push(diagnostic('target-missing', `no element matched selector for target "${target.name}"`, target.name));
-            continue;
+        const attempts = [];
+        let stopStatus;
+        let matchedIndex;
+        let matchedPlaywrightLocator;
+        for (let index = 0; index < target.locators.length; index += 1) {
+            const locator = target.locators[index];
+            const { playwrightLocator, outcome } = await evaluateLocatorAttempt(page, locator);
+            attempts.push({
+                locatorIndex: index,
+                locatorKind: locator.kind,
+                status: outcome.status,
+                ...(outcome.matchCount !== undefined ? { matchCount: outcome.matchCount } : {}),
+            });
+            if (outcome.status === 'matched' && playwrightLocator) {
+                stopStatus = 'matched';
+                matchedIndex = index;
+                matchedPlaywrightLocator = playwrightLocator;
+                break;
+            }
+            if (outcome.status === 'ambiguous') {
+                stopStatus = 'ambiguous';
+                break;
+            }
+            if (outcome.status === 'unavailable') {
+                stopStatus = 'unavailable';
+                break;
+            }
+            // 'not-found': fall through to the next configured locator.
+        }
+        if (stopStatus === 'matched' && matchedPlaywrightLocator && matchedIndex !== undefined) {
+            try {
+                const handles = await matchedPlaywrightLocator.elementHandles();
+                const handle = handles[0];
+                if (handle) {
+                    infos.push({
+                        name: target.name,
+                        attempts,
+                        status: 'matched',
+                        selectedIndex: matchedIndex,
+                        locator: matchedPlaywrightLocator,
+                        handle: handle,
+                    });
+                }
+                else {
+                    infos.push({ name: target.name, attempts, status: 'not-found' });
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                infos.push({ name: target.name, attempts, status: 'unavailable', unavailableReason: `target evaluation failed: ${message}` });
+            }
         }
-        if (matchCount > 1) {
-            targetEvidence[target.name] = ambiguousTargetRecord(matchCount);
-            diagnostics.push(diagnostic('target-ambiguous', `${matchCount} elements matched selector for target "${target.name}"`, target.name));
-            continue;
+        else if (stopStatus === 'ambiguous') {
+            infos.push({ name: target.name, attempts, status: 'ambiguous' });
         }
-        try {
-            targetEvidence[target.name] = await captureResolvedTargetRecord(page, target.selector);
+        else if (stopStatus === 'unavailable') {
+            infos.push({ name: target.name, attempts, status: 'unavailable' });
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const reason = `target evaluation failed: ${message}`;
-            targetEvidence[target.name] = {
-                resolution: {
-                    state: 'available',
-                    source: 'derived',
-                    value: { selectionMethod: 'css-selector', selectionStatus: 'matched' },
-                    derivedFrom: ['selector-query'],
-                },
-                tag: unavailableField(reason),
-                geometry: unavailableField(reason),
-                style: unavailableField(reason),
-                layout: unavailableField(reason),
-                visibility: unavailableField(reason),
-                semantics: unavailableField(reason),
-            };
-            diagnostics.push(diagnostic('browser-evidence-unavailable', reason, target.name));
+        else {
+            infos.push({ name: target.name, attempts, status: 'not-found' });
         }
     }
+    try {
+        // Phase 2: bounded pairwise DOM containment among the configured targets
+        // only (never unconfigured ancestors), in configured target order.
+        const containmentByName = new Map();
+        for (const info of infos) {
+            if (info.status !== 'matched' || !info.handle)
+                continue;
+            const selfHandle = info.handle;
+            const containedByTargetIds = [];
+            const evaluatedTargetIds = [];
+            const unresolvedTargetIds = [];
+            for (const other of infos) {
+                if (other.name === info.name)
+                    continue;
+                if (other.status === 'matched' && other.handle) {
+                    evaluatedTargetIds.push(other.name);
+                    const contains = await other.handle.evaluate((elOther, elSelf) => elOther !== elSelf && elOther.contains(elSelf), selfHandle);
+                    if (contains)
+                        containedByTargetIds.push(other.name);
+                }
+                else {
+                    unresolvedTargetIds.push(other.name);
+                }
+            }
+            containmentByName.set(info.name, containmentEvidence({ containedByTargetIds, evaluatedTargetIds, unresolvedTargetIds }, undefined));
+        }
+        // Phase 3: measure resolved targets and assemble every target's evidence.
+        for (const info of infos) {
+            if (info.status === 'matched' && info.locator && info.handle && info.selectedIndex !== undefined) {
+                try {
+                    const containment = containmentByName.get(info.name) ?? containmentEvidence(undefined, 'containment could not be computed');
+                    const { record, visible } = await captureResolvedTargetRecord(info.locator, info.handle, info.attempts, info.selectedIndex, containment);
+                    targetEvidence[info.name] = record;
+                    if (!visible) {
+                        diagnostics.push(diagnostic('target-hidden', `target "${info.name}" resolved but is not visible`, info.name));
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    const reason = `target evaluation failed: ${message}`;
+                    targetEvidence[info.name] = unresolvedTargetRecord('unavailable', info.attempts, reason, containmentEvidence(undefined, `target itself could not be measured: ${reason}`));
+                    diagnostics.push(diagnostic('browser-evidence-unavailable', reason, info.name));
+                }
+                continue;
+            }
+            const selfUnresolvedReason = `target itself did not resolve (status: ${info.status})`;
+            if (info.status === 'ambiguous') {
+                const lastAttempt = info.attempts[info.attempts.length - 1];
+                const matchCount = lastAttempt?.matchCount ?? 0;
+                targetEvidence[info.name] = unresolvedTargetRecord('ambiguous', info.attempts, `target locator matched ${matchCount} elements; expected exactly one`, containmentEvidence(undefined, selfUnresolvedReason));
+                diagnostics.push(diagnostic('target-ambiguous', `${matchCount} elements matched a locator for target "${info.name}"`, info.name));
+            }
+            else if (info.status === 'unavailable') {
+                const reason = info.unavailableReason ?? `target locator could not be evaluated reliably for "${info.name}"`;
+                targetEvidence[info.name] = unresolvedTargetRecord('unavailable', info.attempts, reason, containmentEvidence(undefined, selfUnresolvedReason));
+                diagnostics.push(diagnostic('browser-evidence-unavailable', reason, info.name));
+            }
+            else {
+                targetEvidence[info.name] = unresolvedTargetRecord('not-found', info.attempts, 'no configured locator matched an element', containmentEvidence(undefined, selfUnresolvedReason));
+                diagnostics.push(diagnostic('target-missing', `no locator matched an element for target "${info.name}"`, info.name));
+            }
+        }
+    }
+    finally {
+        await Promise.all(infos.filter((info) => info.handle).map((info) => info.handle.dispose()));
+    }
     return { targetEvidence, diagnostics };
 }
 //# sourceMappingURL=evidenceCapture.js.map