@qa-ai-stlc/explorer 0.3.0 → 0.5.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC"}

package/dist/naming.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Turns human-meaningful, untrusted text (an accessible name, an ARIA label) into a valid camelCase
+ * identifier, falling back to `fallback` (a domain word guaranteed non-empty, like an element
+ * `kind`) when `text` has no letters or digits at all (e.g. an icon-only "→" accessible name).
+ * Never returns a reserved word or an identifier starting with a digit.
+ */
+export declare function toCamelCaseIdentifier(text: string, fallback: string): string;
+/**
+ * Produces the camelCase export name a registry element's locator module entry will use
+ * (ADR-006). Each call to the returned function assigns one element's name; two elements
+ * resolving to the same base name (e.g. two buttons both named "Submit") get a numeric suffix,
+ * tracked across every call against the same namer, so no two elements it names ever collide.
+ */
+export declare function createElementNamer(): (text: string, fallback: string) => string;
+//# sourceMappingURL=naming.d.ts.map

package/dist/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAiEA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU5E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAQ/E"}

package/dist/naming.js

@@ -0,0 +1,94 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+// Splits on anything that is not a letter or digit, dropping empty segments, so accented and
+// non-Latin text collapses to nothing rather than surviving as invalid identifier characters.
+function wordsOf(text) {
+    return text.split(/[^A-Za-z0-9]+/u).filter((word) => word.length > 0);
+}
+// An accessible name equal to a reserved word ("Export", "Delete") would otherwise produce a
+// locator module export that fails to compile.
+const RESERVED_WORDS = new Set([
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'instanceof',
+    'interface',
+    'let',
+    'new',
+    'null',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'return',
+    'static',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+// `.charAt(0)` (unlike `word[0]`) always returns a plain `string` even under
+// `noUncheckedIndexedAccess`, so this never needs an `undefined` fallback for an empty `word`.
+function upperFirst(word) {
+    return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+}
+/**
+ * Turns human-meaningful, untrusted text (an accessible name, an ARIA label) into a valid camelCase
+ * identifier, falling back to `fallback` (a domain word guaranteed non-empty, like an element
+ * `kind`) when `text` has no letters or digits at all (e.g. an icon-only "→" accessible name).
+ * Never returns a reserved word or an identifier starting with a digit.
+ */
+export function toCamelCaseIdentifier(text, fallback) {
+    const words = wordsOf(text);
+    const source = words.length > 0 ? words : wordsOf(fallback);
+    const identifier = source
+        .map((word, index) => (index === 0 ? word.toLowerCase() : upperFirst(word.toLowerCase())))
+        .join('');
+    if (/^[0-9]/u.test(identifier)) {
+        return `element${upperFirst(identifier)}`;
+    }
+    return RESERVED_WORDS.has(identifier) ? `${identifier}Element` : identifier;
+}
+/**
+ * Produces the camelCase export name a registry element's locator module entry will use
+ * (ADR-006). Each call to the returned function assigns one element's name; two elements
+ * resolving to the same base name (e.g. two buttons both named "Submit") get a numeric suffix,
+ * tracked across every call against the same namer, so no two elements it names ever collide.
+ */
+export function createElementNamer() {
+    const seenNameCounts = new Map();
+    return (text, fallback) => {
+        const base = toCamelCaseIdentifier(text, fallback);
+        const seen = seenNameCounts.get(base) ?? 0;
+        seenNameCounts.set(base, seen + 1);
+        return seen === 0 ? base : `${base}${String(seen + 1)}`;
+    };
+}
+//# sourceMappingURL=naming.js.map

package/dist/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC,6FAA6F;AAC7F,8FAA8F;AAC9F,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,6FAA6F;AAC7F,+CAA+C;AAC/C,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,OAAO;IACP,MAAM;IACN,OAAO;IACP,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,SAAS;IACT,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,OAAO;IACP,SAAS;IACT,KAAK;IACL,UAAU;IACV,IAAI;IACJ,YAAY;IACZ,QAAQ;IACR,IAAI;IACJ,YAAY;IACZ,WAAW;IACX,KAAK;IACL,KAAK;IACL,MAAM;IACN,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,MAAM;IACN,OAAO;IACP,MAAM;IACN,KAAK;IACL,QAAQ;IACR,KAAK;IACL,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;CACR,CAAC,CAAC;AAEH,6EAA6E;AAC7E,+FAA+F;AAC/F,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,QAAgB;IAClE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,MAAM;SACtB,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;SACzF,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,IAAI,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,UAAU,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IAC5C,CAAC;IACD,OAAO,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjD,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;QACnC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC;AACJ,CAAC"}

package/dist/pick-mode.d.ts

@@ -0,0 +1,83 @@
+import { type AuthPage, type ViewportSize } from '@qa-ai-stlc/core';
+import type { InteractiveElement, LocatorCandidate, SelectorElement } from '@qa-ai-stlc/schemas';
+import { type LocatorPolicy } from './synthesize-locators.js';
+/**
+ * One element a human captured by clicking it in the overlay, before locator synthesis: the same
+ * signal `extractPageElements()` reads for a crawled element (development plan section 6.1, "Manual
+ * pick mode"), scoped to the same five interactive tags a crawl recognizes so a picked element
+ * always resolves to a valid `InteractiveElementKind`.
+ */
+export interface PickModeCapture {
+    readonly pickId: string;
+    readonly kind: InteractiveElement['kind'];
+    readonly tagName: string;
+    readonly nthOfType: number;
+    readonly accessibleName?: string;
+    readonly testId?: string;
+    readonly role?: string;
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly htmlId?: string;
+}
+interface PickModeState {
+    readonly done: boolean;
+    readonly captures: readonly PickModeCapture[];
+}
+/**
+ * Injects the pick-mode overlay into the current page (development plan section 6.1): a fixed
+ * toolbar with a "Finish picking" button, plus a capture-phase click listener that records the
+ * clicked element (or its closest interactive ancestor) instead of letting the click reach the
+ * application, so a click on a submit button never actually submits the form (safe mode, AGENTS.md
+ * 12.4). A second call on the same page is a no-op — the overlay is idempotent across re-navigation
+ * within the same pick-mode session.
+ */
+export declare function injectPickModeOverlay(page: AuthPage): Promise<void>;
+/** Reads the overlay's current state: every element captured so far, and whether the human is done. */
+export declare function readPickModeState(page: AuthPage): Promise<PickModeState>;
+export interface WaitForPickModeCompletionOptions {
+    readonly pollIntervalMs?: number;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Injected so tests do not wait on real timers (AGENTS.md 5.5, 13). */
+    readonly wait?: (ms: number) => Promise<void>;
+}
+/**
+ * Polls the overlay until the human clicks "Finish picking" (or the given `signal` cancels the
+ * session), returning every element captured. Never resolves early because nothing was clicked yet:
+ * an empty pick-mode session is a human decision, not a failure, so it only rejects on cancellation
+ * or on exceeding `timeoutMs`.
+ */
+export declare function waitForPickModeCompletion(page: AuthPage, options?: WaitForPickModeCompletionOptions): Promise<readonly PickModeCapture[]>;
+/** One captured element with its locator candidates synthesized and its primary candidate scored. */
+export interface PickModeElement {
+    readonly pickId: string;
+    readonly elementId: string;
+    readonly kind: string;
+    /** The human-meaningful text a confirmed name is derived from, before camelCasing (naming.ts). */
+    readonly defaultNameText: string;
+    readonly locatorCandidates: readonly LocatorCandidate[];
+    readonly stabilityScore: number;
+}
+export interface CapturePickModeElementsOptions {
+    readonly policy?: LocatorPolicy;
+    readonly viewports?: readonly ViewportSize[];
+}
+/**
+ * Synthesizes locator candidates and scores the primary candidate for every element a human
+ * captured, against the live page they were picked from (development plan section 6.1 step 3). The
+ * `elementId` assigned here is the same one a crawl would assign the same element (build-selector-
+ * registry.ts's `computeElementId`), so a page later crawled does not duplicate a manually-picked
+ * entry.
+ */
+export declare function capturePickModeElements(page: AuthPage, url: string, captures: readonly PickModeCapture[], options?: CapturePickModeElementsOptions): Promise<PickModeElement[]>;
+/**
+ * Turns captured, scored elements into `source: 'manual'` registry entries (development plan
+ * section 6.1: "the agent proposes logical names ... the human confirms"). Naming itself never
+ * happens here — the engine makes no model calls (AGENTS.md non-negotiable boundary 1) — so
+ * `nameOverrides` carries whatever name the human confirmed for a given `pickId`; an element with
+ * no override falls back to its `defaultNameText`. Names are deduplicated across the whole batch the
+ * same way a crawled registry's names are (naming.ts's `createElementNamer`).
+ */
+export declare function finalizeManualSelectorEntries(elements: readonly PickModeElement[], nameOverrides: ReadonlyMap<string, string>, generatedAt: string): SelectorElement[];
+export {};
+//# sourceMappingURL=pick-mode.d.ts.map

package/dist/pick-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-mode.d.ts","sourceRoot":"","sources":["../src/pick-mode.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAIjG,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAoIzE;AAwBD,uGAAuG;AACvG,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAM9E;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAUD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAqBrC;AAED,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACxD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC9C;AA6BD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,eAAe,EAAE,CAAC,CA4B5B;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,WAAW,EAAE,MAAM,GAClB,eAAe,EAAE,CAanB"}

package/dist/pick-mode.js

@@ -0,0 +1,265 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { QaError } from '@qa-ai-stlc/core';
+import { computeElementId, elementNameForId } from './build-selector-registry.js';
+import { createElementNamer } from './naming.js';
+import { scoreLocatorStability } from './stability-scoring.js';
+import { synthesizeLocatorCandidates } from './synthesize-locators.js';
+/**
+ * Injects the pick-mode overlay into the current page (development plan section 6.1): a fixed
+ * toolbar with a "Finish picking" button, plus a capture-phase click listener that records the
+ * clicked element (or its closest interactive ancestor) instead of letting the click reach the
+ * application, so a click on a submit button never actually submits the form (safe mode, AGENTS.md
+ * 12.4). A second call on the same page is a no-op — the overlay is idempotent across re-navigation
+ * within the same pick-mode session.
+ */
+export async function injectPickModeOverlay(page) {
+    /* v8 ignore next 95 -- runs in the browser's own V8 instance, invisible to Node coverage */
+    await page.evaluate(() => {
+        const globalWindow = window;
+        if (globalWindow.__qaPickMode !== undefined) {
+            return;
+        }
+        const state = { done: false, captures: [] };
+        globalWindow.__qaPickMode = state;
+        let nextPickId = 1;
+        function accessibleName(element) {
+            const ariaLabel = element.getAttribute('aria-label');
+            if (ariaLabel !== null && ariaLabel.trim().length > 0) {
+                return ariaLabel;
+            }
+            const text = element.textContent.trim();
+            return text.length > 0 ? text : undefined;
+        }
+        function computeRole(element, kind) {
+            const explicit = element.getAttribute('role');
+            if (explicit !== null && explicit.trim().length > 0) {
+                return explicit;
+            }
+            if (kind === 'textarea') {
+                return 'textbox';
+            }
+            if (kind === 'select') {
+                return 'combobox';
+            }
+            if (kind === 'input') {
+                const type = (element.getAttribute('type') ?? 'text').toLowerCase();
+                if (type === 'checkbox' || type === 'radio') {
+                    return type;
+                }
+                if (type === 'button' || type === 'submit' || type === 'reset') {
+                    return 'button';
+                }
+                return 'textbox';
+            }
+            return kind === 'button' || kind === 'link' ? kind : undefined;
+        }
+        function labelText(element) {
+            const id = element.getAttribute('id');
+            if (id !== null && id.length > 0) {
+                const associated = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+                const text = associated?.textContent.trim();
+                if (text !== undefined && text.length > 0) {
+                    return text;
+                }
+            }
+            const wrapping = element.closest('label')?.textContent.trim();
+            return wrapping !== undefined && wrapping.length > 0 ? wrapping : undefined;
+        }
+        function nthOfType(element) {
+            const parent = element.parentElement;
+            if (parent === null) {
+                return 1;
+            }
+            let index = 0;
+            for (const sibling of parent.children) {
+                if (sibling.tagName === element.tagName) {
+                    index += 1;
+                    if (sibling === element) {
+                        return index;
+                    }
+                }
+            }
+            return 1;
+        }
+        const kindByTagName = {
+            a: 'link',
+            button: 'button',
+            input: 'input',
+            select: 'select',
+            textarea: 'textarea',
+        };
+        const overlay = document.createElement('div');
+        overlay.id = 'qa-pick-mode-overlay';
+        overlay.style.cssText =
+            'position:fixed;top:0;right:0;z-index:2147483647;background:#111;color:#fff;' +
+                'padding:8px 12px;font:13px sans-serif;display:flex;gap:8px;align-items:center;';
+        overlay.textContent = 'QA pick mode: click an element to capture it.';
+        const finishButton = document.createElement('button');
+        finishButton.id = 'qa-pick-mode-finish';
+        finishButton.type = 'button';
+        finishButton.textContent = 'Finish picking';
+        finishButton.addEventListener('click', () => {
+            state.done = true;
+        });
+        overlay.appendChild(finishButton);
+        document.body.appendChild(overlay);
+        document.addEventListener('click', (event) => {
+            const target = event.target;
+            if (!(target instanceof Element) || target.closest('#qa-pick-mode-overlay') !== null) {
+                return;
+            }
+            const interactive = target.closest('button, a[href], input, select, textarea');
+            if (interactive === null) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            const tagName = interactive.tagName.toLowerCase();
+            const kind = kindByTagName[tagName] ?? tagName;
+            state.captures.push({
+                pickId: `pick-${String(nextPickId)}`,
+                kind,
+                tagName,
+                nthOfType: nthOfType(interactive),
+                accessibleName: accessibleName(interactive),
+                testId: interactive.getAttribute('data-testid') ?? undefined,
+                role: computeRole(interactive, kind),
+                label: labelText(interactive),
+                placeholder: interactive.getAttribute('placeholder') ?? undefined,
+                htmlId: interactive.getAttribute('id') ?? undefined,
+            });
+            nextPickId += 1;
+        }, { capture: true });
+    });
+}
+function isPickModeCapture(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.pickId === 'string' && typeof record.kind === 'string' && typeof record.tagName === 'string');
+}
+function isPickModeState(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.done === 'boolean' &&
+        Array.isArray(record.captures) &&
+        record.captures.every(isPickModeCapture));
+}
+/** Reads the overlay's current state: every element captured so far, and whether the human is done. */
+export async function readPickModeState(page) {
+    /* v8 ignore next 3 -- runs in the browser's own V8 instance, invisible to Node coverage */
+    const result = await page.evaluate(() => {
+        return window.__qaPickMode;
+    });
+    return isPickModeState(result) ? result : { done: false, captures: [] };
+}
+const DEFAULT_POLL_INTERVAL_MS = 500;
+// A human research session, not a machine operation: generous, but still bounded (AGENTS.md 5.5).
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+function defaultWait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Polls the overlay until the human clicks "Finish picking" (or the given `signal` cancels the
+ * session), returning every element captured. Never resolves early because nothing was clicked yet:
+ * an empty pick-mode session is a human decision, not a failure, so it only rejects on cancellation
+ * or on exceeding `timeoutMs`.
+ */
+export async function waitForPickModeCompletion(page, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const wait = options.wait ?? defaultWait;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        const state = await readPickModeState(page);
+        if (state.done) {
+            return state.captures;
+        }
+        if (Date.now() >= deadline) {
+            throw new QaError('explorer.pick_mode.timeout', `Pick mode did not finish within ${String(timeoutMs)}ms`, { remediation: 'Click "Finish picking" in the overlay once every element has been captured.' });
+        }
+        await wait(pollIntervalMs);
+    }
+}
+function toInteractiveElement(capture) {
+    const element = {
+        kind: capture.kind,
+        tagName: capture.tagName,
+        nthOfType: capture.nthOfType,
+    };
+    if (capture.accessibleName !== undefined) {
+        element.accessibleName = capture.accessibleName;
+    }
+    if (capture.testId !== undefined) {
+        element.testId = capture.testId;
+    }
+    if (capture.role !== undefined) {
+        element.role = capture.role;
+    }
+    if (capture.label !== undefined) {
+        element.label = capture.label;
+    }
+    if (capture.placeholder !== undefined) {
+        element.placeholder = capture.placeholder;
+    }
+    if (capture.htmlId !== undefined) {
+        element.htmlId = capture.htmlId;
+    }
+    return element;
+}
+/**
+ * Synthesizes locator candidates and scores the primary candidate for every element a human
+ * captured, against the live page they were picked from (development plan section 6.1 step 3). The
+ * `elementId` assigned here is the same one a crawl would assign the same element (build-selector-
+ * registry.ts's `computeElementId`), so a page later crawled does not duplicate a manually-picked
+ * entry.
+ */
+export async function capturePickModeElements(page, url, captures, options = {}) {
+    const policy = options.policy ?? 'playwright-default';
+    const elements = [];
+    for (const capture of captures) {
+        const interactiveElement = toInteractiveElement(capture);
+        const candidates = synthesizeLocatorCandidates(interactiveElement, policy);
+        const primary = candidates[0];
+        const stabilityScore = primary === undefined
+            ? 0
+            : await scoreLocatorStability(page, primary, options.viewports === undefined ? {} : { viewports: options.viewports });
+        elements.push({
+            pickId: capture.pickId,
+            elementId: computeElementId(url, interactiveElement),
+            kind: interactiveElement.kind,
+            defaultNameText: elementNameForId(interactiveElement),
+            locatorCandidates: candidates,
+            stabilityScore,
+        });
+    }
+    return elements;
+}
+/**
+ * Turns captured, scored elements into `source: 'manual'` registry entries (development plan
+ * section 6.1: "the agent proposes logical names ... the human confirms"). Naming itself never
+ * happens here — the engine makes no model calls (AGENTS.md non-negotiable boundary 1) — so
+ * `nameOverrides` carries whatever name the human confirmed for a given `pickId`; an element with
+ * no override falls back to its `defaultNameText`. Names are deduplicated across the whole batch the
+ * same way a crawled registry's names are (naming.ts's `createElementNamer`).
+ */
+export function finalizeManualSelectorEntries(elements, nameOverrides, generatedAt) {
+    const nameFor = createElementNamer();
+    return elements.map((element) => ({
+        elementId: element.elementId,
+        name: nameFor(nameOverrides.get(element.pickId) ?? element.defaultNameText, element.kind),
+        kind: element.kind,
+        locatorCandidates: [...element.locatorCandidates],
+        stabilityScore: element.stabilityScore,
+        lastVerifiedAt: generatedAt,
+        pii: false,
+        dynamicText: false,
+        source: 'manual',
+    }));
+}
+//# sourceMappingURL=pick-mode.js.map

package/dist/pick-mode.js.map

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

package/dist/stability-scoring.d.ts

@@ -0,0 +1,19 @@
+import type { AuthPage, PageLocator, ViewportSize } from '@qa-ai-stlc/core';
+import type { LocatorCandidate } from '@qa-ai-stlc/schemas';
+export interface StabilityScoringOptions {
+    /** Viewport sizes checked after uniqueness and reload survival; defaults to desktop/tablet/mobile. */
+    readonly viewports?: readonly ViewportSize[];
+}
+export declare const DEFAULT_VIEWPORTS: readonly ViewportSize[];
+/** Resolves one of P1-08's `LocatorCandidate` values to a live `PageLocator`, by strategy. */
+export declare function resolveCandidateLocator(page: AuthPage, candidate: LocatorCandidate): PageLocator;
+/**
+ * Verifies one locator candidate against the current live page: uniqueness now, then survival
+ * across a reload and across each configured viewport size (development plan section 6.3.5).
+ * Uniqueness is a hard gate — a candidate that does not resolve to exactly one element right now
+ * cannot be called stable, so reload/viewport are never checked against a candidate that has
+ * already failed. The page's original viewport size is restored before returning, so scoring one
+ * element's candidate does not affect the next.
+ */
+export declare function scoreLocatorStability(page: AuthPage, candidate: LocatorCandidate, options?: StabilityScoringOptions): Promise<number>;
+//# sourceMappingURL=stability-scoring.d.ts.map

package/dist/stability-scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability-scoring.d.ts","sourceRoot":"","sources":["../src/stability-scoring.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,sGAAsG;IACtG,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC9C;AAED,eAAO,MAAM,iBAAiB,EAAE,SAAS,YAAY,EAIpD,CAAC;AAkCF,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,GAAG,WAAW,CAmBhG;AAOD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,CAAC,CA0BjB"}

package/dist/stability-scoring.js

@@ -0,0 +1,82 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { QaError } from '@qa-ai-stlc/core';
+export const DEFAULT_VIEWPORTS = [
+    { width: 1280, height: 720 },
+    { width: 768, height: 1024 },
+    { width: 375, height: 667 },
+];
+function parseRoleCandidateValue(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (cause) {
+        throw new QaError('locator-candidate-invalid', `Role locator candidate value is not valid JSON: "${value}".`, { cause });
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.role !== 'string') {
+        throw new QaError('locator-candidate-invalid', `Role locator candidate value has no "role" string: "${value}".`);
+    }
+    const record = parsed;
+    return typeof record.name === 'string'
+        ? { role: record.role, name: record.name }
+        : { role: record.role };
+}
+/** Resolves one of P1-08's `LocatorCandidate` values to a live `PageLocator`, by strategy. */
+export function resolveCandidateLocator(page, candidate) {
+    switch (candidate.strategy) {
+        case 'role': {
+            const { role, name } = parseRoleCandidateValue(candidate.value);
+            return page.getByRole(role, name === undefined ? undefined : { name });
+        }
+        case 'testId':
+            return page.getByTestId(candidate.value);
+        case 'label':
+            return page.getByLabel(candidate.value);
+        case 'placeholder':
+            return page.getByPlaceholder(candidate.value);
+        case 'text':
+            return page.getByText(candidate.value);
+        case 'css':
+            return page.locator(candidate.value);
+        default:
+            throw new QaError('locator-strategy-unknown', `Unknown locator strategy "${candidate.strategy}".`);
+    }
+}
+async function isUniqueMatch(page, candidate) {
+    const count = await resolveCandidateLocator(page, candidate).count();
+    return count === 1;
+}
+/**
+ * Verifies one locator candidate against the current live page: uniqueness now, then survival
+ * across a reload and across each configured viewport size (development plan section 6.3.5).
+ * Uniqueness is a hard gate — a candidate that does not resolve to exactly one element right now
+ * cannot be called stable, so reload/viewport are never checked against a candidate that has
+ * already failed. The page's original viewport size is restored before returning, so scoring one
+ * element's candidate does not affect the next.
+ */
+export async function scoreLocatorStability(page, candidate, options = {}) {
+    if (!(await isUniqueMatch(page, candidate))) {
+        return 0;
+    }
+    const viewports = options.viewports ?? DEFAULT_VIEWPORTS;
+    const originalViewport = page.viewportSize();
+    let survivedChecks = 0;
+    await page.reload();
+    if (await isUniqueMatch(page, candidate)) {
+        survivedChecks += 1;
+    }
+    for (const viewport of viewports) {
+        await page.setViewportSize(viewport);
+        if (await isUniqueMatch(page, candidate)) {
+            survivedChecks += 1;
+        }
+    }
+    if (originalViewport !== null) {
+        await page.setViewportSize(originalViewport);
+    }
+    return survivedChecks / (1 + viewports.length);
+}
+//# sourceMappingURL=stability-scoring.js.map

package/dist/stability-scoring.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-ai-stlc/explorer",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The crawler: route discovery in safe mode, redacted request logging, and the route map every later explorer phase builds on.",
   "type": "module",
   "license": "Apache-2.0",
@@ -28,8 +28,8 @@
     "clean": "node ../../scripts/clean-dir.mjs dist"
   },
   "dependencies": {
-    "@qa-ai-stlc/core": "0.2.1",
-    "@qa-ai-stlc/schemas": "0.3.0"
+    "@qa-ai-stlc/core": "0.3.0",
+    "@qa-ai-stlc/schemas": "0.4.0"
   },
   "devDependencies": {
     "@qa-ai-stlc/test-utils": "0.0.0"