@sdods/core 0.3.2 → 0.5.1

package/dist/config/runner.js

@@ -2,16 +2,51 @@ import { existsSync } from 'node:fs';
 import { join, resolve as resolvePath } from 'node:path';
 import { devices } from '@playwright/test';
 import { cucumberReporter, defineBddConfig } from 'playwright-bdd';
-import { runnerProjectName, runFiles } from '@sdods/contracts';
+import { EVIDENCE_DEFAULTS, RUNNER_SETUP_PHASE, runnerProjectName, runFiles, } from '@sdods/contracts';
 import { coreStepsPatterns } from '../steps/glob.js';
 import { combineTagExpr, normalizeTagExpr } from './tags.js';
 const DEVICE_FOR_BROWSER = {
     chromium: 'Desktop Chrome',
+    edge: 'Desktop Edge',
     firefox: 'Desktop Firefox',
     webkit: 'Desktop Safari',
     'mobile-chrome': 'Pixel 7',
     'mobile-safari': 'iPhone 15',
 };
+/**
+ * Browsers that are a branded channel of an engine rather than the bundled build.
+ *
+ * `devices['Desktop Edge']` only sets an Edge user-agent — its `defaultBrowserType` is still
+ * 'chromium' — so without an explicit channel Playwright launches the bundled Chromium and it
+ * merely claims to be Edge. The channel is what actually starts the browser the user installed.
+ */
+const CHANNEL_FOR_BROWSER = { edge: 'msedge' };
+/** The Playwright channel family a project-level `channel:` belongs to, for compatibility checks. */
+function channelFamily(channel) {
+    return channel.startsWith('msedge') ? 'msedge' : 'chrome';
+}
+/**
+ * The channel a run target launches with.
+ *
+ * A project-level `channel:` refines a branded browser, it does not redirect it: `channel: chrome`
+ * on a project that also runs `edge` must not make the `--edge` target launch Google Chrome, which
+ * would put a browser in the results under another browser's name.
+ */
+function channelFor(browser, projectChannel) {
+    const branded = CHANNEL_FOR_BROWSER[browser];
+    if (!branded) {
+        // Chromium-family engines take whatever the project asked for; other engines have no channels.
+        return browser === 'chromium' || browser === 'mobile-chrome' ? projectChannel : undefined;
+    }
+    if (projectChannel && channelFamily(projectChannel) === channelFamily(branded))
+        return projectChannel;
+    return branded;
+}
+/** The `use` keys that select the browser binary for a run target. */
+function browserUse(browser, projectChannel) {
+    const channel = channelFor(browser, projectChannel);
+    return { ...devices[DEVICE_FOR_BROWSER[browser]], ...(channel ? { channel } : {}) };
+}
 export const DASHBOARD_REPORTER = '@sdods/core/reporters/dashboard';
 /** Convenience for `sdods.runner.config.ts`: read the selection from SDODS_* env vars. */
 export function selectionFromEnv(env = process.env) {
@@ -32,6 +67,7 @@ export function selectionFromEnv(env = process.env) {
         allure: env.SDODS_ALLURE === '1',
         reporters: list(env.SDODS_REPORTERS),
         reporterMode: env.SDODS_REPORTER_MODE || 'default',
+        process: env.SDODS_PROCESS || undefined,
     };
 }
 /** Names (and identity) of the Playwright projects a selection would produce, without side effects. */
@@ -93,32 +129,40 @@ export function buildRunnerConfig(registry, sel = {}) {
         for (const k of Object.keys(envUse))
             if (envUse[k] === undefined)
                 delete envUse[k];
+        const byTag = p.retries?.byTag ?? {};
+        const pushProject = (project) => projects.push(...withRetriesByTag(project, byTag));
+        const { fullyParallel, setup } = runSettings(registry, entry.slug, p, sel.process);
+        // Playwright's own artifacts, per target so each project in a multi-project run keeps its own.
+        const evidenceUse = {
+            screenshot: p.evidence.screenshot,
+            video: p.evidence.video,
+            trace: p.evidence.trace,
+        };
         for (const layer of layers) {
             if (layer === 'recorded') {
                 const recordedDir = join(p.root, 'recorded');
                 if (!existsSync(recordedDir))
                     continue;
                 for (const browser of browsers) {
-                    projects.push({
+                    pushProject({
                         name: runnerProjectName({ project: p.slug, layer, browser }),
                         testDir: recordedDir,
                         testMatch: '**/*.spec.ts',
+                        fullyParallel,
                         snapshotPathTemplate: join(p.root, 'features', '__screenshots__', '{projectName}', '{platform}', '{arg}{ext}'),
                         use: {
-                            ...devices[DEVICE_FOR_BROWSER[browser]],
-                            ...(p.channel && (browser === 'chromium' || browser === 'mobile-chrome')
-                                ? { channel: p.channel }
-                                : {}),
+                            ...browserUse(browser, p.channel),
                             baseURL: cfg.env.ui.baseUrl,
                             testIdAttribute: p.testIdAttribute,
                             ...envUse,
+                            ...evidenceUse,
                             sdods: { project: p.slug, layer, browser },
                         },
                     });
                 }
                 continue;
             }
-            const testDir = defineBddConfig({
+            const generate = (tags, outDir) => defineBddConfig({
                 features: `${toPosix(p.root)}/features/**/*.feature`,
                 steps: [
                     ...coreStepsPatterns(cfg.project.steps?.core?.exclude ?? []),
@@ -127,42 +171,66 @@ export function buildRunnerConfig(registry, sel = {}) {
                 ],
                 // Each run generates into its own dir (cleaned by `sdods run`), lint/export into `.lint`,
                 // so concurrent runs and tooling never race on generated specs.
-                outputDir: `${toPosix(join(cfg.runtime.repoRoot, '.sdods/generated', sel.lint ? '.lint' : (sel.runId ?? 'adhoc'), p.slug, layer))}`,
+                outputDir: `${toPosix(join(cfg.runtime.repoRoot, '.sdods/generated', sel.lint ? '.lint' : (sel.runId ?? 'adhoc'), p.slug, outDir))}`,
                 featuresRoot: `${toPosix(p.root)}/features`,
                 // Explicit: scenarios that only use core steps cannot let bddgen guess the project test instance.
                 importTestFrom: `${toPosix(p.root)}/steps/fixtures.ts`,
                 disableWarnings: { importTestFrom: true },
-                tags: combineTagExpr(`@${layer}`, sel.tags),
+                tags,
                 examplesTitleFormat: 'Example #<_index_>',
                 missingSteps: sel.lint ? 'fail-on-gen' : 'fail-on-run',
                 aiFix: { promptAttachment: true },
                 quotes: 'single',
             });
+            const layerExpr = combineTagExpr(`@${layer}`, sel.tags);
+            // Setup scenarios are generated on their own: whatever --tags selects, the gate still runs,
+            // and a scenario that is setup never runs a second time inside the target it gates.
+            const testDir = generate(setup ? `(${layerExpr}) and not (${setup.tags})` : layerExpr, layer);
             bddConfigs++;
+            const setupTestDir = setup
+                ? generate(combineTagExpr(`@${layer}`, setup.tags), `${layer}--${RUNNER_SETUP_PHASE}`)
+                : undefined;
+            if (setupTestDir)
+                bddConfigs++;
+            /** Push a target, preceded by its setup companion when the project has a setup tier. */
+            const pushTarget = (parts, target) => {
+                const name = runnerProjectName({ project: p.slug, ...parts });
+                if (setupTestDir) {
+                    const setupName = runnerProjectName({
+                        project: p.slug,
+                        ...parts,
+                        phase: RUNNER_SETUP_PHASE,
+                    });
+                    projects.push({ ...target, name: setupName, testDir: setupTestDir });
+                    pushProject({ ...target, name, testDir, dependencies: [setupName] });
+                }
+                else {
+                    pushProject({ ...target, name, testDir });
+                }
+            };
             if (layer === 'api') {
-                projects.push({
-                    name: runnerProjectName({ project: p.slug, layer }),
-                    testDir,
-                    use: { sdods: { project: p.slug, layer } },
+                pushTarget({ layer }, {
+                    fullyParallel,
+                    use: {
+                        ...evidenceUse,
+                        sdods: { project: p.slug, layer },
+                    },
                 });
                 continue;
             }
             for (const browser of browsers) {
-                projects.push({
-                    name: runnerProjectName({ project: p.slug, layer, browser }),
-                    testDir,
+                pushTarget({ layer, browser }, {
+                    fullyParallel,
                     // Baselines live with the project (generated specs are per-run and deleted):
                     // projects/<slug>/features/__screenshots__/<pw project>/<platform>/<name>.png
                     snapshotPathTemplate: join(p.root, 'features', '__screenshots__', '{projectName}', '{platform}', '{arg}{ext}'),
                     use: {
-                        ...devices[DEVICE_FOR_BROWSER[browser]],
-                        ...(p.channel && (browser === 'chromium' || browser === 'mobile-chrome')
-                            ? { channel: p.channel }
-                            : {}),
+                        ...browserUse(browser, p.channel),
                         baseURL: cfg.env.ui.baseUrl,
                         testIdAttribute: p.testIdAttribute,
                         viewport: browser.startsWith('mobile') ? undefined : p.screenshots.viewport,
                         ...envUse,
+                        ...evidenceUse,
                         sdods: { project: p.slug, layer, browser },
                     },
                 });
@@ -227,13 +295,16 @@ export function buildRunnerConfig(registry, sel = {}) {
         expect: { timeout: timeouts.expect },
         retries,
         workers,
-        fullyParallel: true,
+        // Each generated project sets its own; this is the fallback for anything added by hand.
+        fullyParallel: first
+            ? runSettings(registry, first.project.slug, first.project, sel.process).fullyParallel
+            : true,
         outputDir: join(runDir, runFiles.output),
         reporter,
         use: {
-            screenshot: 'off',
-            video: 'retain-on-failure',
-            trace: 'on-first-retry',
+            screenshot: first?.project.evidence.screenshot ?? EVIDENCE_DEFAULTS.screenshot,
+            video: first?.project.evidence.video ?? EVIDENCE_DEFAULTS.video,
+            trace: first?.project.evidence.trace ?? EVIDENCE_DEFAULTS.trace,
             actionTimeout: timeouts.action,
             navigationTimeout: timeouts.navigation,
             // Playwright's own `--headed` flag still wins on the CLI; this is what makes the documented
@@ -248,6 +319,66 @@ export function buildRunnerConfig(registry, sel = {}) {
         },
     };
 }
+/**
+ * `retries.byTag` as runner projects.
+ *
+ * Retries are fixed when a test is collected: Playwright takes them from the enclosing
+ * `test.describe.configure` or the project, and offers no runtime setter; bddgen has no hook to
+ * add `@retries:N` to a scenario it did not read from the feature file. What Playwright does
+ * offer is project-level `grep`, matched against the title AND the tags. So each byTag entry
+ * becomes a sibling of the project — same name, so `--project <name>`, reports and dashboards are
+ * unchanged — that greps for the tag and carries its retries, and the base project inverts every
+ * byTag grep. Entries are ordered by retries, highest first, and each sibling also inverts the
+ * ones before it, so a scenario with two such tags runs exactly once, with the larger count.
+ *
+ * Explicit `--retries` on the CLI still overrides every project, these included. A scenario's own
+ * `@retries:N` tag (playwright-bdd) wins over all of it.
+ */
+export function withRetriesByTag(project, byTag) {
+    const entries = Object.entries(byTag)
+        .map(([tag, retries]) => ({ tag: tag.startsWith('@') ? tag : `@${tag}`, retries }))
+        .sort((a, b) => b.retries - a.retries);
+    if (!entries.length)
+        return [project];
+    // Whitespace-delimited: Playwright joins the title path and tags with spaces, so `@flaky`
+    // must not match `@flakyish`. (A scenario TITLE containing the literal tag also matches.)
+    const tagRe = (tag) => new RegExp(`(^|\\s)${tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`);
+    const seen = [];
+    const out = [];
+    for (const { tag, retries } of entries) {
+        const re = tagRe(tag);
+        out.push({
+            ...project,
+            grep: re,
+            ...(seen.length ? { grepInvert: [...seen] } : {}),
+            retries,
+        });
+        seen.push(re);
+    }
+    return [{ ...project, grepInvert: seen }, ...out];
+}
+/**
+ * `fullyParallel` and the setup tier for one project, with a named process taking precedence.
+ * A process that is not defined for this project (a multi-project run) leaves the project's own.
+ */
+function runSettings(registry, slug, project, processName) {
+    const proc = processName
+        ? registry.processesOf(slug).find((x) => x.name === processName)
+        : undefined;
+    return {
+        fullyParallel: proc?.fullyParallel ?? project.fullyParallel,
+        setup: setupTierOf(project, proc),
+    };
+}
+/**
+ * The setup tier a run uses: the process's `setup` (`false` turns it off), else the project's.
+ * Tags are normalised like `--tags`, so `setup: { tags: setup }` means `@setup`.
+ */
+export function setupTierOf(project, proc) {
+    const setup = proc?.setup === false ? undefined : (proc?.setup ?? project.setup);
+    const tags = normalizeTagExpr(setup?.tags);
+    return tags ? { tags } : undefined;
+}
 function parseEnvOverrides() {
     const raw = process.env.SDODS_CLI_OVERRIDES;
     if (!raw)

package/dist/config/tags.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectConfig } from '@sdods/contracts';
+import { type ProjectConfig } from '@sdods/contracts';
 export declare const LAYER_TAGS: readonly ["@ui", "@api", "@hybrid"];
 /** Control tags the runner interprets itself; lint passes them through untouched. */
 export declare const RUNNER_SPECIAL_TAGS: RegExp;
@@ -6,7 +6,11 @@ export declare const RUNNER_SPECIAL_TAGS: RegExp;
 export declare const PLAYWRIGHT_BDD_SPECIAL: RegExp;
 export declare const VALUE_TAG: RegExp;
 export declare const KNOWN_VALUE_TAGS: readonly ["env", "user", "data", "har", "jira", "github", "skip", "title", "flag"];
-export declare const BROWSERS_FOR_SKIP: readonly ["chromium", "firefox", "webkit", "mobile-chrome", "mobile-safari"];
+/**
+ * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser
+ * to `BrowserSchema` is the only edit needed — and the lint message lists the new name for free.
+ */
+export declare const BROWSERS_FOR_SKIP: ("chromium" | "edge" | "firefox" | "webkit" | "mobile-chrome" | "mobile-safari")[];
 export interface TagTaxonomy {
     layers: readonly string[];
     suites: string[];
@@ -24,6 +28,14 @@ export declare function suiteOfTags(tags: readonly string[], suites: readonly st
 export declare function combineTagExpr(layerTag: string, userExpr?: string): string;
 /** `--tags @smoke` shorthand also accepts comma lists ("@smoke,@sanity" → "@smoke or @sanity"). */
 export declare function normalizeTagExpr(input?: string): string | undefined;
+export interface TagExpr {
+    evaluate(tags: readonly string[]): boolean;
+}
+/**
+ * Parse a Cucumber tag expression, or fail as a configuration error (exit 2) that quotes it.
+ * Every command that selects scenarios by tag goes through here so they agree on what matches.
+ */
+export declare function parseTagExpr(expr: string): TagExpr;
 export interface TagGateContext {
     /** `config.env.name` — the environment this run is actually pointed at. */
     env: string;

package/dist/config/tags.js

@@ -1,3 +1,6 @@
+import parseInfix from 'cucumber-tag-expressions';
+import { BrowserSchema } from '@sdods/contracts';
+import { SdodsError } from '../errors.js';
 export const LAYER_TAGS = ['@ui', '@api', '@hybrid'];
 /** Control tags the runner interprets itself; lint passes them through untouched. */
 export const RUNNER_SPECIAL_TAGS = /^@(only|skip|fixme|fail|slow|timeout:\d+|retries:\d+|mode:(parallel|serial|default))$/;
@@ -15,13 +18,11 @@ export const KNOWN_VALUE_TAGS = [
     'title',
     'flag',
 ];
-export const BROWSERS_FOR_SKIP = [
-    'chromium',
-    'firefox',
-    'webkit',
-    'mobile-chrome',
-    'mobile-safari',
-];
+/**
+ * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser
+ * to `BrowserSchema` is the only edit needed — and the lint message lists the new name for free.
+ */
+export const BROWSERS_FOR_SKIP = BrowserSchema.options;
 export function taxonomyFromProject(project) {
     return {
         layers: LAYER_TAGS,
@@ -75,6 +76,25 @@ export function normalizeTagExpr(input) {
         .map((t) => (t.startsWith('@') ? t : `@${t}`));
     return parts.length > 1 ? parts.join(' or ') : parts[0];
 }
+// The package is CommonJS with `exports.default`; ESM interop may hand back the module object.
+const parseInfixFn = (parseInfix.default ??
+    parseInfix);
+/**
+ * Parse a Cucumber tag expression, or fail as a configuration error (exit 2) that quotes it.
+ * Every command that selects scenarios by tag goes through here so they agree on what matches.
+ */
+export function parseTagExpr(expr) {
+    try {
+        const node = parseInfixFn(expr);
+        return { evaluate: (tags) => node.evaluate([...tags]) };
+    }
+    catch (e) {
+        throw new SdodsError('CONFIG_INVALID', `Invalid tag expression "${expr}": ${e.message}`, {
+            hint: 'Combine tags with and / or / not and balanced parentheses, e.g. "@ui and (@smoke or @sanity)".',
+            exitCode: 2,
+        });
+    }
+}
 /**
  * Why this scenario should not run here, or undefined to run it.
  *

package/dist/fixtures/api-context.d.ts

@@ -30,6 +30,13 @@ export declare class ApiContext {
         name: string;
         value: string;
     } | null | undefined;
+    /**
+     * Send through a request context with an empty cookie jar instead of the shared `request`
+     * fixture. On @ui/@hybrid the shared context starts from the leased role's storageState, so a
+     * "credential X alone is refused" assertion would otherwise pass on the session cookie.
+     * Set by `I use an isolated API client`.
+     */
+    isolated: boolean;
     /** step index → number of calls made during that step (for attachment numbering) */
     readonly callsByStep: Map<number, number>;
     get lastResponse(): ApiSnapshot['response'] | undefined;

package/dist/fixtures/api-context.js

@@ -18,6 +18,13 @@ export class ApiContext {
      * refused. Any suite whose env declared `api.auth` had a no-op step.
      */
     auth;
+    /**
+     * Send through a request context with an empty cookie jar instead of the shared `request`
+     * fixture. On @ui/@hybrid the shared context starts from the leased role's storageState, so a
+     * "credential X alone is refused" assertion would otherwise pass on the session cookie.
+     * Set by `I use an isolated API client`.
+     */
+    isolated = false;
     /** step index → number of calls made during that step (for attachment numbering) */
     callsByStep = new Map();
     get lastResponse() {

package/dist/fixtures/auth.js

@@ -1,6 +1,77 @@
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { Logger } from '../logger.js';
+function originOf(url) {
+    try {
+        const o = new URL(url).origin;
+        return o === 'null' ? undefined : o;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Restore one origin's localStorage into a live context without navigating (#99).
+ *
+ * This used to `page.goto(origin)` and write the keys from there. An app that sends a signed-in
+ * visitor away from `/` on the client then had a redirect chain still running when the step
+ * returned, and the scenario's first `page.goto` was aborted (`net::ERR_ABORTED`). The context
+ * already exists by the time a step leases a user, so `newContext({ storageState })` is not an
+ * option here (the `@user:<role>` tag path does use it, via `ensure`).
+ *
+ * - Page already on the origin: write the keys straight into it. Nothing navigates.
+ * - Otherwise: a context init script writes them in the first document of that origin, before the
+ *   app's own scripts run, in any page of the context.
+ *
+ * Planted ONCE per context, not on every navigation. An init script left in place would run again
+ * on each document, so an app that signs out (clears storage) and navigates would be silently
+ * signed back in and a logout scenario would pass while proving nothing. The script is therefore
+ * disposed once a document of that origin has reached DOMContentLoaded (by then it has certainly
+ * run). A navigation that commits in the short window before the dispose lands can run it again;
+ * it only writes keys that are absent, so it never overwrites what the app wrote meanwhile.
+ *
+ * Only localStorage is restored, as before: storageState carries no sessionStorage or IndexedDB.
+ */
+async function plantLocalStorage(context, page, origin, items) {
+    if (originOf(page.url()) === origin) {
+        await page.evaluate((entries) => {
+            for (const { name, value } of entries)
+                window.localStorage.setItem(name, value);
+        }, items);
+        return;
+    }
+    const script = await context.addInitScript(({ origin: target, entries }) => {
+        if (location.origin !== target)
+            return;
+        try {
+            for (const { name, value } of entries) {
+                if (window.localStorage.getItem(name) === null)
+                    window.localStorage.setItem(name, value);
+            }
+        }
+        catch {
+            // storage disabled for this document (sandboxed frame): nothing to plant into
+        }
+    }, { origin, entries: items });
+    const watched = new Set();
+    let disposed = false;
+    const onLoaded = (p) => {
+        if (disposed || originOf(p.url()) !== origin)
+            return;
+        disposed = true;
+        context.off('page', watch);
+        for (const w of watched)
+            w.off('domcontentloaded', onLoaded);
+        void script.dispose().catch(() => undefined);
+    };
+    const watch = (p) => {
+        watched.add(p);
+        p.on('domcontentloaded', onLoaded);
+    };
+    context.on('page', watch);
+    for (const p of context.pages())
+        watch(p);
+}
 /** How long another worker may hold the refresh lock before we treat it as crashed. */
 const LOCK_STALE_MS = 90_000;
 const LOCK_POLL_MS = 250;
@@ -142,11 +213,7 @@ export class AuthStateCache {
         for (const origin of state.origins ?? []) {
             if (!origin.localStorage?.length)
                 continue;
-            await page.goto(origin.origin, { waitUntil: 'domcontentloaded' }).catch(() => undefined);
-            await page.evaluate((items) => {
-                for (const { name, value } of items)
-                    window.localStorage.setItem(name, value);
-            }, origin.localStorage);
+            await plantLocalStorage(context, page, origin.origin, origin.localStorage);
         }
         return true;
     }

package/dist/fixtures/test.js

@@ -3,7 +3,7 @@ import { test as base, createBdd } from 'playwright-bdd';
 import { ProjectRegistry } from '../config/registry.js';
 import { parseTagValue, scenarioSkipReason } from '../config/tags.js';
 import { noopAuth } from '../auth/index.js';
-import { ApiClient } from '../api/client.js';
+import { ApiClient, isolatedRequestFactory } from '../api/client.js';
 import { CompositeDataProvider } from '../data/provider.js';
 import { FileUserPool } from '../data/user-pool.js';
 import { apiHarForScenario } from '../har/hooks.js';
@@ -151,9 +151,15 @@ export const test = base.extend({
     apiContext: async ({}, use) => {
         await use(new ApiContext());
     },
-    api: async ({ request, config, apiContext, scenario, harMode, $bddContext, $tags }, use, testInfo) => {
+    // `request` is Playwright's shared APIRequestContext. It is seeded from the test's context
+    // options, so on @ui/@hybrid it carries the leased role's storageState cookies (plus any cookie
+    // a response sets); on @api storageState is undefined and it starts empty. The isolated context
+    // behind `I use an isolated API client` is only created when a scenario asks for it.
+    api: async ({ request, playwright, config, apiContext, scenario, harMode, $bddContext, $tags }, use, testInfo) => {
+        const isolated = isolatedRequestFactory(playwright.request);
         await use(new ApiClient({
             request,
+            isolatedRequest: isolated.get,
             config,
             ctx: apiContext,
             testInfo,
@@ -161,6 +167,7 @@ export const test = base.extend({
             stepIndex: () => $bddContext.stepIndex,
             har: apiHarForScenario({ $tags, config, harMode }),
         }));
+        await isolated.dispose();
     },
     data: async ({ config, scenario, apiContext }, use, testInfo) => {
         const provider = new CompositeDataProvider(config, { seed: scenario.fingerprint });

package/dist/heal/healer.d.ts

@@ -46,11 +46,22 @@ export declare class Healer {
     select(primary: Locator, ctx: HealContext, value: string): Promise<void>;
     expectVisible(primary: Locator, ctx: HealContext): Promise<void>;
     expectText(primary: Locator, ctx: HealContext, text: string | RegExp): Promise<void>;
+    /**
+     * The first of `locators`, in preference order, that matches anything. Waits up to
+     * primaryTimeoutMs for the LAST one to attach — callers list the loosest locator last, a
+     * superset of the others — so an element that renders a moment late is still judged by the
+     * most precise locator. When nothing matches, the most precise one is returned for resolve()
+     * to wait on and heal from.
+     */
+    prefer(...locators: [Locator, ...Locator[]]): Promise<Locator>;
     /**
      * Wait briefly for the primary locator; on failure probe all candidates in parallel,
-     * score them and pick the best above minScore. Records a HealEvent either way.
+     * score them and pick the best above minScore. A primary that is visible but matches several
+     * elements is healed too, for actions that have a role to prefer. Records a HealEvent whenever
+     * it heals.
      */
     resolve(primary: Locator, ctx: HealContext, action: HealAction): Promise<Locator>;
+    private heal;
     private probe;
     private record;
 }