@anweat/dsh-browser 0.1.15 → 0.2.0-rc.1

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;