@anweat/dsh-browser 0.1.17 → 0.2.0

package/lib/journal.js

@@ -0,0 +1,238 @@
+/**
+ * The exploration journal: a bounded, in-memory record of what one session did through `browser_call`.
+ *
+ * It is evidence for turning an exploration into a draft (`automation.develop` draft_from_journal), not a
+ * log of the page. Entries hold the action, the page generation before and after, the locator, scrubbed
+ * parameters, and the outcome. Typed text never appears in an entry: fill/type text is a reference
+ * `{ref:'v<seq>', length, sensitive?}`. The text itself is kept in memory only when it is short (at most
+ * {@link RAW_TEXT_MAX} characters) and does not look secret (see {@link looksSecret}), and only so a draft
+ * can use it as a literal or an example; it is released together with its entry, and nothing is written to disk.
+ * @module dsh-browser/journal
+ */
+/** Default number of entries a session keeps; the oldest are dropped first. */
+export const JOURNAL_LIMIT = 200;
+/** Typed text longer than this is never retained, only its length. */
+export const RAW_TEXT_MAX = 200;
+// --- what counts as secret -----------------------------------------------------
+/** Field names that suggest a secret; the same list `observe.read` uses for controls. */
+export const SENSITIVE_NAME = /(^|[^a-z])(pass(word|wd|phrase|code)?|pwd|secret|token|api[-_ ]?key|credential|bearer|jwt|otp|csrf|xsrf|session[-_ ]?(id|key)?|ssn|cvv|cvc|private[-_ ]?key|authori[sz]ation|auth[-_ ]?(token|key|code)|one[-_ ]?time[-_ ]?code|card[-_ ]?(number|num|no)|cc[-_ ]?(number|num|csc|exp)|iban|account[-_ ]?(number|num))([^a-z]|$)/i;
+function camel(value) { return value.replace(/([a-z])([A-Z])/g, '$1 $2'); }
+export function cardLike(value) {
+    const digits = value.replace(/[ -]/g, '');
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let digit = Number(digits[digits.length - 1 - i]);
+        if (i % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return sum % 10 === 0;
+}
+export function tokenLike(value) {
+    if (cardLike(value))
+        return true;
+    if (value.length < 20 || /\s/.test(value))
+        return false;
+    if (/^eyJ[\w-]+\.[\w-]+\.[\w-]*$/.test(value))
+        return true;
+    return /^[A-Za-z0-9_\-+/=.~]+$/.test(value) && /\d/.test(value) && /[A-Za-z]/.test(value);
+}
+/** A value that looks like a token, a JWT or a card number. */
+export function looksSecret(value) {
+    return tokenLike(value);
+}
+/** A locator that names a password-like field (its label, name, css...). */
+export function locatorSuggestsSecret(locator) {
+    if (!locator)
+        return false;
+    const parts = [locator.name, locator.label, locator.text, locator.testId, locator.selector, locator.css].filter((part) => typeof part === 'string');
+    return parts.some(part => SENSITIVE_NAME.test(camel(part)));
+}
+/** `https://u:p@host/path?token=x` -> secret query values and userinfo removed. Returns the cleaned URL and whether anything was removed. */
+export function redactUrl(value) {
+    try {
+        const parsed = new URL(value);
+        let redacted = false;
+        if (parsed.username || parsed.password) {
+            parsed.username = '';
+            parsed.password = '';
+            redacted = true;
+        }
+        for (const key of [...parsed.searchParams.keys()]) {
+            const raw = parsed.searchParams.get(key) ?? '';
+            if (SENSITIVE_NAME.test(camel(key)) || /token|key|auth|session|cookie|password|secret/i.test(key) || tokenLike(raw)) {
+                parsed.searchParams.set(key, '[redacted]');
+                redacted = true;
+            }
+        }
+        return { url: parsed.toString().slice(0, 2_000), redacted };
+    }
+    catch {
+        return { url: value.slice(0, 200), redacted: false };
+    }
+}
+// --- scrubbing a call's arguments ---------------------------------------------
+/** Arguments that steer a call but carry no value worth keeping. */
+const SKIP = new Set(['locator', 'selector', 'expectGeneration']);
+/** Text typed into a control: always a reference. */
+const TYPED = new Set(['act.fill', 'act.type']);
+function clip(value, max = 200) { return value.length > max ? value.slice(0, max) + '…' : value; }
+function normalizeLocator(args) {
+    const given = args.locator;
+    if (typeof args.selector === 'string' && given === undefined)
+        return { css: clip(args.selector, 500) };
+    if (!given || typeof given !== 'object' || Array.isArray(given))
+        return undefined;
+    const copy = {};
+    for (const [key, value] of Object.entries(given)) {
+        if (typeof value === 'string')
+            copy[key === 'selector' ? 'css' : key] = clip(value, 500);
+        else
+            copy[key] = value;
+    }
+    return copy;
+}
+/** A short plain value kept as is; anything long or secret-looking becomes a reference. */
+function scrubValue(value, seq, index = 0) {
+    if (typeof value !== 'string')
+        return value;
+    if (value.length > RAW_TEXT_MAX || looksSecret(value))
+        return { ref: `v${seq}${index ? '.' + index : ''}`, length: value.length, ...looksSecret(value) ? { sensitive: true } : {} };
+    return value;
+}
+/**
+ * Scrub the arguments of one call. `sensitiveControl` is true when the page itself says the target is a
+ * password-like control (type=password, autocomplete one-time-code, ...).
+ */
+export function scrubCall(action, args, seq, sensitiveControl = false) {
+    const locator = normalizeLocator(args);
+    const params = {};
+    let raw;
+    for (const [key, value] of Object.entries(args)) {
+        if (SKIP.has(key) || value === undefined)
+            continue;
+        if (typeof value === 'string') {
+            if (TYPED.has(action) && key === 'text') {
+                const sensitive = sensitiveControl || locatorSuggestsSecret(locator) || looksSecret(value);
+                params[key] = { ref: `v${seq}`, length: value.length, ...sensitive ? { sensitive: true } : {} };
+                if (!sensitive && value.length <= RAW_TEXT_MAX)
+                    raw = value;
+            }
+            else if (key === 'url')
+                params[key] = redactUrl(value).url;
+            else if (['expression', 'source', 'code', 'script'].includes(key))
+                params[key] = { ref: `v${seq}`, length: value.length };
+            else
+                params[key] = scrubValue(value, seq);
+        }
+        else if (Array.isArray(value)) {
+            if (key === 'files')
+                params.files = { count: value.length, names: value.slice(0, 5).map(file => clip(String(file).split(/[\\/]/).pop() ?? '', 80)) };
+            else if (['steps', 'recipe'].includes(key))
+                params[key] = { count: value.length };
+            else
+                params[key] = value.slice(0, 20).map((entry, index) => scrubValue(entry, seq, index + 1));
+        }
+        else if (value && typeof value === 'object') {
+            // inputs and the like: only the names, never the values.
+            params[key] = { keys: Object.keys(value).slice(0, 10) };
+        }
+        else
+            params[key] = value;
+    }
+    return { params, ...locator ? { locator } : {}, ...raw !== undefined ? { raw } : {} };
+}
+// --- which calls are journaled -------------------------------------------------
+const JOURNALED_GROUPS = new Set(['target', 'observe', 'act', 'script']);
+const JOURNALED_EXTRA = new Set(['automation.run_recipe', 'automation.run']);
+/** Calls that only read the page: observation points, never steps. */
+const OBSERVATIONS = new Set(['observe.read', 'observe.screenshot']);
+/** Whether a call goes into the journal. Lists, inspection, searches and drafting are not exploration. */
+export function isJournaled(action) {
+    if (action === 'target.list')
+        return false;
+    return JOURNALED_GROUPS.has(action.split('.')[0]) || JOURNALED_EXTRA.has(action);
+}
+export function isObservation(action) {
+    return OBSERVATIONS.has(action);
+}
+/** What a finished call changed, from what it is and how it ended. */
+export function effectsOf(mutating, outcome) {
+    if (!mutating)
+        return 'none';
+    if (outcome.ok)
+        return 'observed';
+    if (outcome.executionStatus === 'outcome_unknown')
+        return 'unknown';
+    const never = ['LOCATOR_NOT_FOUND', 'LOCATOR_AMBIGUOUS', 'NOT_ACTIONABLE', 'TARGET_STALE', 'INVALID_ARGS', 'TARGET_CLOSED', 'POLICY_DENIED', 'INVALID_RECIPE'];
+    return outcome.errorCode && never.includes(outcome.errorCode) ? 'none' : 'unknown';
+}
+// --- the journal itself --------------------------------------------------------
+export class SessionJournal {
+    limit;
+    nextSeq = 1;
+    items = [];
+    raws = new Map();
+    /** How many entries fell off the front because of the limit. */
+    dropped = 0;
+    constructor(limit = JOURNAL_LIMIT) {
+        this.limit = limit;
+    }
+    /** Reserve the sequence number of a call that is about to run. */
+    allocate() {
+        return this.nextSeq++;
+    }
+    add(entry, raw) {
+        this.items.push(entry);
+        if (this.items.length > 1 && this.items[this.items.length - 2].seq > entry.seq)
+            this.items.sort((a, b) => a.seq - b.seq);
+        if (raw !== undefined)
+            this.raws.set(entry.seq, raw);
+        while (this.items.length > this.limit) {
+            const gone = this.items.shift();
+            this.raws.delete(gone.seq);
+            this.dropped += 1;
+        }
+    }
+    entries() {
+        return this.items;
+    }
+    /** The retained typed text of an entry, if it was short and not secret. Internal: never part of an entry. */
+    rawText(seq) {
+        return this.raws.get(seq);
+    }
+    get firstSeq() { return this.items[0]?.seq; }
+    get lastSeq() { return this.items[this.items.length - 1]?.seq; }
+    get size() { return this.items.length; }
+    clear() {
+        this.items = [];
+        this.raws.clear();
+    }
+}
+/** The one-line summary of a finished call, with no secret query values. */
+export function summarize(action, envelope) {
+    if (!envelope.ok)
+        return clip(`${envelope.error?.code ?? 'FAILED'}: ${String(envelope.error?.message ?? '').split('\n')[0]}`, 140);
+    const result = envelope.result ?? {};
+    const parts = [];
+    if (typeof result.title === 'string' && result.title)
+        parts.push(clip(result.title, 60));
+    if (typeof result.url === 'string' && result.url) {
+        try {
+            const parsed = new URL(redactUrl(result.url).url);
+            parts.push(parsed.pathname + parsed.search);
+        }
+        catch {
+            parts.push(clip(result.url, 80));
+        }
+    }
+    if (typeof result.text === 'string' && isObservation(action))
+        parts.push(`${result.text.length} chars`);
+    return clip(parts.join(' | ') || 'ok', 140);
+}
+//# sourceMappingURL=journal.js.map

package/lib/journal.js.map

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

package/lib/locator.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One locator contract for atomic actions and v2 recipe steps.
+ *
+ * A locator is strict by default: it must match exactly one element. When it
+ * matches several, the step is not performed and the caller gets
+ * {@link LocatorAmbiguousError} with a short summary of the first candidates, so
+ * the model can tell which element it meant instead of acting on whichever one
+ * happened to come first. Choosing one anyway takes an explicit `index` with an
+ * `indexReason`; `explicitFirst` is the marker a v1 migration leaves behind for
+ * "this used to be `.first()`".
+ * @module dsh-browser/locator
+ */
+export interface BrowserFrameSpec {
+    selector?: string;
+    name?: string;
+    url?: string;
+}
+export interface BrowserLocatorSpec {
+    /** CSS selector. `css` is accepted as an alias (the v2 recipe spelling). */
+    selector?: string;
+    css?: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    label?: string;
+    testId?: string;
+    exact?: boolean;
+    /** Atomic-action iframe: exactly one of selector, name, url. */
+    frame?: BrowserFrameSpec;
+    /** Nested iframes, outermost first, each a CSS selector for an iframe element. */
+    framePath?: string[];
+    /** Pick the n-th match (0-based). Requires `indexReason`. */
+    index?: number;
+    indexReason?: string;
+    /** Take the first match without an ambiguity error. Set by the v1 converter; meant to be resolved later. */
+    explicitFirst?: boolean;
+}
+export type BrowserTarget = string | BrowserLocatorSpec;
+/** What one of several matches looks like, enough to choose between them. */
+export interface LocatorCandidate {
+    index: number;
+    role: string;
+    name: string;
+    text: string;
+    visible: boolean;
+}
+export interface LocatorAmbiguity {
+    total: number;
+    items: LocatorCandidate[];
+}
+/** Raised instead of acting when a strict locator matches more than one element. */
+export declare class LocatorAmbiguousError extends Error {
+    readonly ambiguity: LocatorAmbiguity;
+    constructor(message: string, ambiguity: LocatorAmbiguity);
+}
+/** Where a page stands now: what a stale caller needs to re-bind to it. */
+export interface PageGeneration {
+    targetId: string;
+    generation: number;
+}
+/** Raised, before anything is done, when `expectGeneration` is not the page's current generation. */
+export declare class TargetStaleError extends Error {
+    readonly current: PageGeneration;
+    constructor(message: string, current: PageGeneration);
+}
+export declare const MAX_CANDIDATES = 5;
+/** Check a locator's shape. Throws a message the model can act on; used before resolving and when a recipe is saved. */
+export declare function validateLocatorSpec(spec: unknown, label?: string): BrowserLocatorSpec;
+/**
+ * Build the Playwright locator for a target. No `.first()` unless the spec asks
+ * for it, so Playwright's own strict-mode check stays in force.
+ */
+export declare function resolveLocator(page: any, target: BrowserTarget): any;
+/** The first candidates of a locator, best effort: a failure here must not hide the ambiguity itself. */
+export declare function describeCandidates(locator: any): Promise<LocatorAmbiguity>;
+export declare function formatCandidates(ambiguity: LocatorAmbiguity): string;
+/**
+ * Run an action on a strict locator. If the locator turns out to match several
+ * elements, nothing was acted on (Playwright checks before it acts) and the
+ * error is upgraded with the candidate summary.
+ */
+export declare function withStrictLocator<T>(locator: any, run: (locator: any) => Promise<T>): Promise<T>;

package/lib/locator.js

@@ -0,0 +1,190 @@
+/**
+ * One locator contract for atomic actions and v2 recipe steps.
+ *
+ * A locator is strict by default: it must match exactly one element. When it
+ * matches several, the step is not performed and the caller gets
+ * {@link LocatorAmbiguousError} with a short summary of the first candidates, so
+ * the model can tell which element it meant instead of acting on whichever one
+ * happened to come first. Choosing one anyway takes an explicit `index` with an
+ * `indexReason`; `explicitFirst` is the marker a v1 migration leaves behind for
+ * "this used to be `.first()`".
+ * @module dsh-browser/locator
+ */
+/** Raised instead of acting when a strict locator matches more than one element. */
+export class LocatorAmbiguousError extends Error {
+    ambiguity;
+    constructor(message, ambiguity) {
+        super(message);
+        this.ambiguity = ambiguity;
+        this.name = 'LocatorAmbiguousError';
+    }
+}
+/** Raised, before anything is done, when `expectGeneration` is not the page's current generation. */
+export class TargetStaleError extends Error {
+    current;
+    constructor(message, current) {
+        super(message);
+        this.current = current;
+        this.name = 'TargetStaleError';
+    }
+}
+const MODES = ['selector', 'css', 'role', 'text', 'label', 'testId'];
+const KNOWN_KEYS = new Set([...MODES, 'name', 'exact', 'frame', 'framePath', 'index', 'indexReason', 'explicitFirst']);
+const MAX_FRAME_PATH = 5;
+export const MAX_CANDIDATES = 5;
+function bounded(value, label, max) {
+    if (typeof value !== 'string' || value.length < 1 || value.length > max)
+        throw new Error(`${label} must contain 1 to ${max} characters`);
+    return value;
+}
+/** Check a locator's shape. Throws a message the model can act on; used before resolving and when a recipe is saved. */
+export function validateLocatorSpec(spec, label = 'browser target') {
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec))
+        throw new Error(`${label} must be a selector string or locator object`);
+    const value = spec;
+    for (const key of Object.keys(value))
+        if (!KNOWN_KEYS.has(key))
+            throw new Error(`${label} has an unsupported field "${key}"; use ${[...KNOWN_KEYS].join(', ')}`);
+    const modes = MODES.filter(mode => value[mode] !== undefined);
+    if (modes.length !== 1)
+        throw new Error(`${label} requires exactly one of selector (css), role, text, label, or testId`);
+    if (value.name !== undefined && value.role === undefined)
+        throw new Error(`${label} name is only valid with role`);
+    if (value.exact !== undefined && typeof value.exact !== 'boolean')
+        throw new Error(`${label} exact must be a boolean`);
+    if (value.index !== undefined) {
+        if (!Number.isInteger(value.index) || value.index < 0 || value.index > 1000)
+            throw new Error(`${label} index must be an integer from 0 to 1000`);
+        if (typeof value.indexReason !== 'string' || !value.indexReason.trim())
+            throw new Error(`${label} index requires indexReason: say why this match and not the others`);
+    }
+    if (value.indexReason !== undefined && value.index === undefined)
+        throw new Error(`${label} indexReason is only valid with index`);
+    if (value.index !== undefined && value.explicitFirst)
+        throw new Error(`${label} cannot combine index and explicitFirst`);
+    if (value.explicitFirst !== undefined && typeof value.explicitFirst !== 'boolean')
+        throw new Error(`${label} explicitFirst must be a boolean`);
+    if (value.frame !== undefined && value.framePath !== undefined)
+        throw new Error(`${label} cannot combine frame and framePath`);
+    if (value.framePath !== undefined) {
+        if (!Array.isArray(value.framePath) || value.framePath.length < 1 || value.framePath.length > MAX_FRAME_PATH)
+            throw new Error(`${label} framePath must list 1 to ${MAX_FRAME_PATH} iframe selectors`);
+        value.framePath.forEach(entry => bounded(entry, `${label} framePath entry`, 500));
+    }
+    if (value.frame !== undefined) {
+        const frameModes = [value.frame.selector, value.frame.name, value.frame.url].filter(entry => entry !== undefined);
+        if (frameModes.length !== 1)
+            throw new Error('browser frame requires exactly one of selector, name, or url');
+    }
+    return value;
+}
+/**
+ * Build the Playwright locator for a target. No `.first()` unless the spec asks
+ * for it, so Playwright's own strict-mode check stays in force.
+ */
+export function resolveLocator(page, target) {
+    if (!target || (typeof target !== 'string' && typeof target !== 'object'))
+        throw new Error('browser target must be a selector string or locator object');
+    const spec = validateLocatorSpec(typeof target === 'string' ? { selector: target } : target);
+    let root = page;
+    if (spec.frame) {
+        if (spec.frame.selector)
+            root = page.frameLocator(bounded(spec.frame.selector, 'frame selector', 500));
+        else {
+            const frame = page.frame(spec.frame.name
+                ? { name: bounded(spec.frame.name, 'frame name', 500) }
+                : { url: bounded(spec.frame.url, 'frame url', 2_000) });
+            if (!frame)
+                throw new Error('browser target frame was not found');
+            root = frame;
+        }
+    }
+    for (const entry of spec.framePath ?? [])
+        root = root.frameLocator(entry);
+    const css = spec.selector ?? spec.css;
+    let locator;
+    if (css !== undefined)
+        locator = root.locator(bounded(css, 'selector', 500));
+    else if (spec.role !== undefined) {
+        locator = root.getByRole(bounded(spec.role, 'role', 100), {
+            ...spec.name !== undefined ? { name: bounded(spec.name, 'role name', 2_000) } : {},
+            exact: spec.exact ?? false,
+        });
+    }
+    else if (spec.text !== undefined)
+        locator = root.getByText(bounded(spec.text, 'text locator', 2_000), { exact: spec.exact ?? false });
+    else if (spec.label !== undefined)
+        locator = root.getByLabel(bounded(spec.label, 'label locator', 2_000), { exact: spec.exact ?? false });
+    else
+        locator = root.getByTestId(bounded(spec.testId, 'testId', 500));
+    if (spec.index !== undefined)
+        return locator.nth(spec.index);
+    if (spec.explicitFirst)
+        return locator.first();
+    return locator;
+}
+/** Summarize the matches of an ambiguous locator, in the page. A raw string: it must not carry transpiler helpers. */
+const SUMMARIZE = `(els) => {
+  const implicit = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox', img: 'img', ul: 'list', ol: 'list', li: 'listitem', nav: 'navigation', main: 'main', table: 'table', form: 'form', h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading', summary: 'button', dialog: 'dialog' }
+  const inputRole = { checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button', image: 'button', range: 'slider', search: 'searchbox', number: 'spinbutton' }
+  const named = ['button', 'link', 'heading', 'menuitem', 'tab', 'option', 'checkbox', 'radio', 'listitem']
+  return els.slice(0, ${MAX_CANDIDATES}).map((el, index) => {
+    const tag = el.tagName.toLowerCase()
+    let role = el.getAttribute('role') || ''
+    if (!role) role = tag === 'input' ? (inputRole[(el.getAttribute('type') || 'text').toLowerCase()] || 'textbox') : (implicit[tag] || '')
+    const text = String(el.innerText || el.textContent || el.value || '').trim().replace(/\\s+/g, ' ')
+    let name = el.getAttribute('aria-label') || ''
+    if (!name && el.labels && el.labels.length) name = el.labels[0].innerText || ''
+    if (!name) name = el.getAttribute('title') || el.getAttribute('placeholder') || el.getAttribute('alt') || ''
+    if (!name && named.includes(role)) name = text
+    const rect = el.getBoundingClientRect()
+    const style = getComputedStyle(el)
+    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.display !== 'none'
+    return { index, role: role || tag, name: String(name).trim().slice(0, 80), text: text.slice(0, 80), visible }
+  })
+}`;
+/** The first candidates of a locator, best effort: a failure here must not hide the ambiguity itself. */
+export async function describeCandidates(locator) {
+    let total = 0;
+    let items = [];
+    try {
+        total = Number(await locator.count()) || 0;
+    }
+    catch { /* keep 0 */ }
+    try {
+        // Playwright treats a plain string as an expression, not a function; a Function built from the string serializes as one.
+        const rows = await locator.evaluateAll(new Function('els', `return (${SUMMARIZE})(els)`));
+        if (Array.isArray(rows))
+            items = rows.slice(0, MAX_CANDIDATES).map((row, index) => ({
+                index: typeof row?.index === 'number' ? row.index : index,
+                role: String(row?.role ?? ''), name: String(row?.name ?? ''), text: String(row?.text ?? ''), visible: row?.visible !== false,
+            }));
+    }
+    catch { /* the summary is optional */ }
+    return { total: Math.max(total, items.length), items };
+}
+export function formatCandidates(ambiguity) {
+    const rows = ambiguity.items.map(item => `#${item.index} ${item.role}${item.name ? ' ' + JSON.stringify(item.name) : ''}${item.text && item.text !== item.name ? ' text ' + JSON.stringify(item.text) : ''} ${item.visible ? 'visible' : 'hidden'}`);
+    return rows.join('; ') + (ambiguity.total > ambiguity.items.length ? `; …${ambiguity.total - ambiguity.items.length} more` : '');
+}
+function isStrictViolation(error) {
+    return !(error instanceof LocatorAmbiguousError) && /strict mode violation/i.test(error instanceof Error ? error.message : String(error));
+}
+/**
+ * Run an action on a strict locator. If the locator turns out to match several
+ * elements, nothing was acted on (Playwright checks before it acts) and the
+ * error is upgraded with the candidate summary.
+ */
+export async function withStrictLocator(locator, run) {
+    try {
+        return await run(locator);
+    }
+    catch (error) {
+        if (!isStrictViolation(error))
+            throw error;
+        const ambiguity = await describeCandidates(locator);
+        const first = (error instanceof Error ? error.message : String(error)).split('\n')[0];
+        throw new LocatorAmbiguousError(`Locator matched ${ambiguity.total || 'more than one'} elements, so nothing was done. Candidates: ${formatCandidates(ambiguity) || '(unavailable)'}. Make the locator unique (role+name, exact, label, testId, frame), or pass index with indexReason. [${first}]`, ambiguity);
+    }
+}
+//# sourceMappingURL=locator.js.map

package/lib/locator.js.map

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

package/lib/observe-script.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The in-page half of observe.read: one function, shipped to the page as source text.
+ *
+ * It is a raw string on purpose: it runs inside the page, so it must not carry transpiler helpers, and
+ * it must not use template literals (the string is written with String.raw). It reads the DOM and
+ * returns plain data; it never changes the page. The only thing it leaves behind is a WeakMap stored
+ * under a registered symbol on each scanned window, which maps each listed element to its number, so
+ * that the Node side can later prove that a candidate locator points at that very element.
+ *
+ * Coverage: the document, open shadow roots (recursively), and same-origin iframes (recursively, up to
+ * the frame-path limit). A cross-origin or sandboxed iframe is listed as a frame with its limitation,
+ * never entered. Closed shadow roots cannot be seen from page script and are not covered.
+ * @module dsh-browser/observe-script
+ */
+/** Symbol (registered with Symbol.for) under which each scanned window keeps its element-number map. */
+export declare const OBSERVE_SYMBOL = "dsh.observe";
+/** Maximum iframe nesting the scan enters; matches the locator framePath limit. */
+export declare const OBSERVE_MAX_FRAME_DEPTH = 5;
+/** Maximum number of iframes entered in one observation. */
+export declare const OBSERVE_MAX_FRAMES = 20;
+/** Reads, in the element's own window, the numbers of the elements a locator matched. */
+export declare const IDENTITY_SOURCE: string;
+/**
+ * `(root, opts) => result`. `root` is a Document or the Element an observation is scoped to.
+ * opts: { controls, links, tables, maxItems, includeValues, region?, maxFrameDepth, maxFrames }.
+ */
+export declare const OBSERVE_SOURCE: string;