@sdods/core 0.7.2 → 0.9.0

package/dist/config/emulation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-scenario browser emulation from tags: `@locale:<bcp47>`, `@timezone:<IANA>`,
+ * `@theme:<light|dark|no-preference>`, `@viewport:<W>x<H>` and `@device:<name>`.
+ *
+ * Six locales × dark/light used to mean twelve env yamls, because the only place a browser
+ * context's locale and colour scheme could be set was the env's `use:` block. The tags move that
+ * axis onto the scenario (or a Feature, or a tagged `Examples:` block), so one env file covers
+ * every combination.
+ *
+ * Locale and timezone are fixed when Playwright creates the browser context and cannot be
+ * changed afterwards, which is why these are tags resolved by fixtures before the context opens,
+ * rather than steps. Precedence, highest first: the tag, then the env's `use:`, then Playwright's
+ * default. `@viewport:` wins over the viewport of `@device:`.
+ *
+ * Kept pure (no fixtures, no browser) so the precedence and the validation that lint shares with
+ * the runtime are testable on their own — the `scenarioSkipReason` precedent.
+ */
+export declare const EMULATION_TAGS: readonly ["locale", "timezone", "theme", "viewport", "device"];
+export type EmulationTag = (typeof EMULATION_TAGS)[number];
+export declare const COLOR_SCHEMES: readonly ["light", "dark", "no-preference"];
+export type ColorScheme = (typeof COLOR_SCHEMES)[number];
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+export interface EmulatedDevice {
+    /** The Playwright device descriptor name, e.g. `iPhone 15`. */
+    name: string;
+    userAgent: string;
+    viewport: ViewportSize;
+    deviceScaleFactor: number;
+    isMobile: boolean;
+    hasTouch: boolean;
+}
+export interface Emulation {
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: ColorScheme;
+    viewport?: ViewportSize;
+    device?: EmulatedDevice;
+}
+/** `320x640` → `{ width: 320, height: 640 }`, or undefined when it is not a usable size. */
+export declare function parseViewport(value: string): ViewportSize | undefined;
+/**
+ * A tag value cannot contain a space, and every Playwright device name does (`iPhone 15`,
+ * `Galaxy S9+`). Names match case-insensitively with any run of spaces, hyphens or underscores
+ * treated as one separator, so `@device:iPhone-15` and `@device:iphone_15` both find `iPhone 15`.
+ */
+export declare function findDevice(value: string): string | undefined;
+/** Why `@<key>:<value>` is unusable, or undefined when it is fine. Shared by lint and runtime. */
+export declare function emulationTagProblem(key: EmulationTag, value: string): string | undefined;
+/**
+ * The emulation a scenario's tags ask for. Keys the tags do not mention are absent, so the
+ * caller falls back to whatever the env or Playwright would have used.
+ *
+ * Throws on an unusable value or on two different values for the same key: lint reports both
+ * first, and a scenario that reaches the runner anyway must fail loudly rather than run under
+ * an emulation nobody asked for.
+ */
+export declare function emulationFromTags(tags: readonly string[]): Emulation;
+/** The browser-context option values a scenario gets: tags first, then what the project resolved. */
+export interface ContextEmulationBase {
+    locale?: string;
+    timezoneId?: string;
+    colorScheme?: ColorScheme | null;
+    viewport?: ViewportSize | null;
+    userAgent?: string;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    hasTouch?: boolean;
+    browserName?: string;
+}
+export declare function applyEmulation<T extends ContextEmulationBase>(base: T, emulation: Emulation): Omit<T, 'browserName'>;
+//# sourceMappingURL=emulation.d.ts.map

package/dist/config/emulation.js

@@ -0,0 +1,154 @@
+import { devices } from '@playwright/test';
+import { SdodsError } from '../errors.js';
+import { parseTagValues } from './tags.js';
+/**
+ * Per-scenario browser emulation from tags: `@locale:<bcp47>`, `@timezone:<IANA>`,
+ * `@theme:<light|dark|no-preference>`, `@viewport:<W>x<H>` and `@device:<name>`.
+ *
+ * Six locales × dark/light used to mean twelve env yamls, because the only place a browser
+ * context's locale and colour scheme could be set was the env's `use:` block. The tags move that
+ * axis onto the scenario (or a Feature, or a tagged `Examples:` block), so one env file covers
+ * every combination.
+ *
+ * Locale and timezone are fixed when Playwright creates the browser context and cannot be
+ * changed afterwards, which is why these are tags resolved by fixtures before the context opens,
+ * rather than steps. Precedence, highest first: the tag, then the env's `use:`, then Playwright's
+ * default. `@viewport:` wins over the viewport of `@device:`.
+ *
+ * Kept pure (no fixtures, no browser) so the precedence and the validation that lint shares with
+ * the runtime are testable on their own — the `scenarioSkipReason` precedent.
+ */
+export const EMULATION_TAGS = ['locale', 'timezone', 'theme', 'viewport', 'device'];
+export const COLOR_SCHEMES = ['light', 'dark', 'no-preference'];
+/** `320x640` → `{ width: 320, height: 640 }`, or undefined when it is not a usable size. */
+export function parseViewport(value) {
+    const m = /^(\d{1,5})x(\d{1,5})$/.exec(value.trim());
+    if (!m)
+        return undefined;
+    const width = Number(m[1]);
+    const height = Number(m[2]);
+    return width > 0 && height > 0 ? { width, height } : undefined;
+}
+/**
+ * A tag value cannot contain a space, and every Playwright device name does (`iPhone 15`,
+ * `Galaxy S9+`). Names match case-insensitively with any run of spaces, hyphens or underscores
+ * treated as one separator, so `@device:iPhone-15` and `@device:iphone_15` both find `iPhone 15`.
+ */
+export function findDevice(value) {
+    if (value in devices)
+        return value;
+    const norm = (s) => s.toLowerCase().replace(/[\s_-]+/g, '-');
+    const wanted = norm(value);
+    return Object.keys(devices).find((name) => norm(name) === wanted);
+}
+/** Why `@<key>:<value>` is unusable, or undefined when it is fine. Shared by lint and runtime. */
+export function emulationTagProblem(key, value) {
+    switch (key) {
+        case 'locale':
+            try {
+                // Throws RangeError on anything that is not a structurally valid BCP 47 tag.
+                Intl.getCanonicalLocales(value);
+                return undefined;
+            }
+            catch {
+                return `@locale:${value} is not a BCP 47 locale (e.g. fr, fr-FR, pt-BR${value.includes('_') ? ' — use a hyphen, not an underscore' : ''}).`;
+            }
+        case 'timezone':
+            try {
+                // Accepts every IANA zone and its aliases (UTC, Etc/GMT+1) — `Intl.supportedValuesOf`
+                // lists canonical names only, so it would reject `UTC` on some runtimes.
+                new Intl.DateTimeFormat('en-US', { timeZone: value });
+                return undefined;
+            }
+            catch {
+                return `@timezone:${value} is not an IANA time zone (e.g. Europe/Paris, America/New_York, UTC).`;
+            }
+        case 'theme':
+            return COLOR_SCHEMES.includes(value)
+                ? undefined
+                : `@theme:${value} must be one of ${COLOR_SCHEMES.join(', ')}.`;
+        case 'viewport':
+            return parseViewport(value)
+                ? undefined
+                : `@viewport:${value} must be <width>x<height> in CSS pixels (e.g. @viewport:320x640).`;
+        case 'device':
+            return findDevice(value)
+                ? undefined
+                : `@device:${value} is not a Playwright device. Write the descriptor name with hyphens for spaces (e.g. @device:iPhone-15, @device:Pixel-7).`;
+    }
+}
+/**
+ * The emulation a scenario's tags ask for. Keys the tags do not mention are absent, so the
+ * caller falls back to whatever the env or Playwright would have used.
+ *
+ * Throws on an unusable value or on two different values for the same key: lint reports both
+ * first, and a scenario that reaches the runner anyway must fail loudly rather than run under
+ * an emulation nobody asked for.
+ */
+export function emulationFromTags(tags) {
+    const one = (key) => {
+        const values = [...new Set(parseTagValues(tags, key))];
+        if (values.length > 1)
+            throw new SdodsError('CONFIG_INVALID', `Conflicting tags @${key}:${values.join(` and @${key}:`)} on one scenario.`, {
+                hint: `A scenario runs in one browser context, so it takes one @${key}: value. Tags on the Feature apply to every scenario in it — remove the duplicate from the scenario or the Feature.`,
+            });
+        const value = values[0];
+        if (value === undefined)
+            return undefined;
+        const problem = emulationTagProblem(key, value);
+        if (problem)
+            throw new SdodsError('CONFIG_INVALID', problem, { hint: 'Run `sdods lint`.' });
+        return value;
+    };
+    const out = {};
+    const locale = one('locale');
+    // Canonical form (`fr-fr` → `fr-FR`), so the context and `I use the locale` agree on spelling.
+    if (locale)
+        out.locale = Intl.getCanonicalLocales(locale)[0];
+    const timezone = one('timezone');
+    if (timezone)
+        out.timezoneId = timezone;
+    const theme = one('theme');
+    if (theme)
+        out.colorScheme = theme;
+    const viewport = one('viewport');
+    if (viewport)
+        out.viewport = parseViewport(viewport);
+    const deviceTag = one('device');
+    if (deviceTag) {
+        const name = findDevice(deviceTag);
+        const d = devices[name];
+        out.device = {
+            name,
+            userAgent: d.userAgent,
+            viewport: d.viewport,
+            deviceScaleFactor: d.deviceScaleFactor,
+            isMobile: d.isMobile,
+            hasTouch: d.hasTouch,
+        };
+    }
+    return out;
+}
+export function applyEmulation(base, emulation) {
+    const { browserName, ...rest } = base;
+    const d = emulation.device;
+    return {
+        ...rest,
+        ...(emulation.locale !== undefined ? { locale: emulation.locale } : {}),
+        ...(emulation.timezoneId !== undefined ? { timezoneId: emulation.timezoneId } : {}),
+        ...(emulation.colorScheme !== undefined ? { colorScheme: emulation.colorScheme } : {}),
+        ...(d
+            ? {
+                viewport: d.viewport,
+                userAgent: d.userAgent,
+                deviceScaleFactor: d.deviceScaleFactor,
+                hasTouch: d.hasTouch,
+                // Firefox rejects `isMobile` at context creation. The engine is the run target's, so a
+                // device tag on the firefox target emulates size, agent and touch only.
+                ...(browserName === 'firefox' ? {} : { isMobile: d.isMobile }),
+            }
+            : {}),
+        ...(emulation.viewport !== undefined ? { viewport: emulation.viewport } : {}),
+    };
+}
+//# sourceMappingURL=emulation.js.map

package/dist/config/index.d.ts

@@ -7,4 +7,5 @@ export * from './resolve.js';
 export * from './registry.js';
 export * from './workspace.js';
 export * from './runner.js';
+export * from './emulation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.js

@@ -7,4 +7,5 @@ export * from './resolve.js';
 export * from './registry.js';
 export * from './workspace.js';
 export * from './runner.js';
+export * from './emulation.js';
 //# sourceMappingURL=index.js.map

package/dist/config/resolve.js

@@ -93,7 +93,7 @@ export function resolveConfig(opts) {
     markAll(envYaml, prov, 'envYaml', 'env');
     // env-level overrides of project sections
     let projectMerged = project;
-    for (const section of ['screenshots', 'heal', 'timeouts', 'perf', 'evidence']) {
+    for (const section of ['screenshots', 'heal', 'timeouts', 'perf', 'a11y', 'evidence']) {
         const patch = envYaml[section];
         if (patch) {
             projectMerged = {

package/dist/config/runner.js

@@ -228,7 +228,10 @@ export function buildRunnerConfig(registry, sel = {}) {
                         ...browserUse(browser, p.channel),
                         baseURL: cfg.env.ui.baseUrl,
                         testIdAttribute: p.testIdAttribute,
-                        viewport: browser.startsWith('mobile') ? undefined : p.screenshots.viewport,
+                        // Mobile targets keep their device descriptor's viewport. The key must be ABSENT, not
+                        // `undefined`: Playwright treats an explicit undefined option as "use the default",
+                        // so `viewport: undefined` reset Pixel 7 and iPhone 15 to a 1280x720 desktop window.
+                        ...(browser.startsWith('mobile') ? {} : { viewport: p.screenshots.viewport }),
                         ...envUse,
                         ...evidenceUse,
                         sdods: { project: p.slug, layer, browser },

package/dist/config/tags.d.ts

@@ -5,7 +5,7 @@ export declare const RUNNER_SPECIAL_TAGS: RegExp;
 /** @deprecated Use {@link RUNNER_SPECIAL_TAGS}. Removed in the next minor. */
 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 KNOWN_VALUE_TAGS: readonly ["env", "user", "data", "har", "jira", "github", "skip", "title", "flag", "matrix", "req", "locale", "timezone", "theme", "viewport", "device"];
 /**
  * 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.

package/dist/config/tags.js

@@ -17,6 +17,13 @@ export const KNOWN_VALUE_TAGS = [
     'skip',
     'title',
     'flag',
+    'matrix',
+    'req',
+    'locale',
+    'timezone',
+    'theme',
+    'viewport',
+    'device',
 ];
 /**
  * Values `@skip:<browser>` accepts. Derived from the schema rather than copied, so adding a browser

package/dist/data/index.d.ts

@@ -4,4 +4,5 @@ export * from './loaders.js';
 export * from './provider.js';
 export * from './user-pool.js';
 export * from './factories.js';
+export * from './pool-capacity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/data/index.js

@@ -4,4 +4,5 @@ export * from './loaders.js';
 export * from './provider.js';
 export * from './user-pool.js';
 export * from './factories.js';
+export * from './pool-capacity.js';
 //# sourceMappingURL=index.js.map

package/dist/data/pool-capacity.d.ts

@@ -0,0 +1,58 @@
+import type { BrowserName, Layer, UserPoolConfig } from '@sdods/contracts';
+import type { ResolvedConfig } from '../config/resolve.js';
+import { SdodsError } from '../errors.js';
+export interface PoolDemandOptions {
+    /** Selected layers; `recorded` has no Gherkin and takes no `@user:` lease. */
+    layers: readonly Layer[];
+    /** Selected browsers (each is its own run target for ui/hybrid). */
+    browsers: readonly BrowserName[];
+    /** `--tags`, already normalised. */
+    tags?: string;
+    /** The setup tier's tags: those scenarios run before the targets they gate, not beside them. */
+    setupTags?: string;
+    /** Feature flags the env declares (`env.vars.features`); undefined gates nothing. */
+    flags?: readonly string[];
+    quarantine?: 'run' | 'skip';
+    fullyParallel: boolean;
+    /** Keep a feature, given its path relative to the project root. */
+    includeFeature?: (projectRelativePath: string) => boolean;
+    /** Keep a scenario by name (`--scenario` / `--grep`, matched on the scenario name only). */
+    includeScenario?: (name: string) => boolean;
+    repeatEach?: number;
+    shardTotal?: number;
+}
+/**
+ * For each `@user:<role>`, how many units of work that lease it could run at once: one per
+ * scenario per run target, or one per feature file per target where the file runs serially
+ * (`fullyParallel: false`, `@mode:serial`, `@mode:default`).
+ */
+export declare function poolDemandByRole(project: {
+    root: string;
+}, env: string, o: PoolDemandOptions): Map<string, number>;
+export interface PoolShortfall {
+    role: string;
+    /** Accounts with this role after `env.users.poolSize`. */
+    accounts: number;
+    /** Scenarios (or serial files) with this role that the workers could run at once. */
+    concurrent: number;
+}
+/**
+ * Roles whose exclusive, worker-held leases cannot cover the workers that will ask for them.
+ *
+ * Empty whenever contention cannot starve a worker: `mode: shared` takes no lease,
+ * `leaseScope: scenario` queues instead of starving, and a dataset that is not file-backed has no
+ * count to compare. A role with no account at all is not a capacity problem — it fails at any
+ * worker count, and the lease names the roles that do exist.
+ */
+export declare function checkPoolCapacity(opts: {
+    pool: UserPoolConfig | undefined;
+    accounts: ReadonlyMap<string, number> | undefined;
+    demand: ReadonlyMap<string, number>;
+    workers: number;
+}): PoolShortfall[];
+/** Accounts per role for the resolved env, after `env.users.poolSize`. Undefined if not file-backed. */
+export declare function poolAccountsFor(config: ResolvedConfig): Map<string, number> | undefined;
+/** How the worker count was arrived at, for messages. */
+export declare function describeWorkers(workers: number | undefined): string;
+export declare function poolTooSmallError(config: ResolvedConfig, shortfalls: readonly PoolShortfall[], runtimeWorkers: number | undefined): SdodsError;
+//# sourceMappingURL=pool-capacity.d.ts.map

package/dist/data/pool-capacity.js

@@ -0,0 +1,138 @@
+import { cpus } from 'node:os';
+import { relative } from 'node:path';
+import { combineTagExpr, parseTagExpr, parseTagValue, scenarioSkipReason } from '../config/tags.js';
+import { SdodsError } from '../errors.js';
+import { parseFeatureFile } from '../lint/gherkin.js';
+import { listFeatureFiles } from '../lint/index.js';
+import { poolAccountsByEnv } from '../matrix/index.js';
+import { effectiveWorkers, leaseWaitMs } from './user-pool.js';
+/**
+ * #153: an exclusive lease is held for a worker's whole life, so a role with fewer accounts than
+ * the workers that reach its scenarios starves every other worker. Each one waits `waitMs` and
+ * fails the scenario with USER_POOL_EXHAUSTED, once per scenario, 30s into it. Measured on a real
+ * suite: 55 passed / 335 failed at --workers 4 with one `member` account. This decides that before
+ * any spec is generated.
+ *
+ * It must never cry wolf, so every estimate below errs towards FEWER concurrent leases: a scenario
+ * the tag gate would skip, a filter only approximated here, or a shard's share all count low.
+ */
+/** Playwright's `browserName` for an SDODS browser: what the runtime tag gate compares `@skip:` with. */
+const ENGINE = {
+    chromium: 'chromium',
+    edge: 'chromium',
+    firefox: 'firefox',
+    webkit: 'webkit',
+    'mobile-chrome': 'chromium',
+    'mobile-safari': 'webkit',
+};
+/**
+ * For each `@user:<role>`, how many units of work that lease it could run at once: one per
+ * scenario per run target, or one per feature file per target where the file runs serially
+ * (`fullyParallel: false`, `@mode:serial`, `@mode:default`).
+ */
+export function poolDemandByRole(project, env, o) {
+    const setup = o.setupTags ? parseTagExpr(o.setupTags) : undefined;
+    const layers = o.layers
+        .filter((l) => l !== 'recorded')
+        .map((layer) => ({ layer, expr: parseTagExpr(combineTagExpr(`@${layer}`, o.tags)) }));
+    const units = new Map();
+    for (const file of listFeatureFiles(project.root)) {
+        const rel = relative(project.root, file).replace(/\\/g, '/');
+        if (o.includeFeature && !o.includeFeature(rel))
+            continue;
+        const parsed = parseFeatureFile(file);
+        for (const pickle of parsed.pickles) {
+            const tags = pickle.tags.map((t) => t.name);
+            const role = parseTagValue(tags, 'user');
+            if (!role || setup?.evaluate(tags))
+                continue;
+            if (o.includeScenario && !o.includeScenario(pickle.name))
+                continue;
+            const serial = tags.includes('@mode:serial') ||
+                tags.includes('@mode:default') ||
+                (!o.fullyParallel && !tags.includes('@mode:parallel'));
+            for (const { layer, expr } of layers) {
+                if (!expr.evaluate(tags))
+                    continue;
+                const targets = layer === 'api' ? [undefined] : o.browsers;
+                for (const browser of targets) {
+                    const gate = { env, flags: o.flags, quarantine: o.quarantine };
+                    // The runtime gate sees Playwright's engine name; lint accepts the SDODS name. Skipped
+                    // under either reading counts as skipped, which can only lower the estimate.
+                    if (scenarioSkipReason(tags, gate) ||
+                        (browser &&
+                            (scenarioSkipReason(tags, { ...gate, browser }) ||
+                                scenarioSkipReason(tags, { ...gate, browser: ENGINE[browser] }))))
+                        continue;
+                    const key = `${layer}|${browser ?? ''}|${rel}${serial ? '' : `|${pickle.id}`}`;
+                    let set = units.get(role);
+                    if (!set)
+                        units.set(role, (set = new Set()));
+                    set.add(key);
+                }
+            }
+        }
+    }
+    const out = new Map();
+    for (const [role, set] of units) {
+        let n = set.size * Math.max(1, o.repeatEach ?? 1);
+        // A shard runs some share of the tests; the smallest guaranteed share is the honest estimate.
+        if (o.shardTotal && o.shardTotal > 1)
+            n = Math.floor(n / o.shardTotal);
+        out.set(role, n);
+    }
+    return out;
+}
+/**
+ * Roles whose exclusive, worker-held leases cannot cover the workers that will ask for them.
+ *
+ * Empty whenever contention cannot starve a worker: `mode: shared` takes no lease,
+ * `leaseScope: scenario` queues instead of starving, and a dataset that is not file-backed has no
+ * count to compare. A role with no account at all is not a capacity problem — it fails at any
+ * worker count, and the lease names the roles that do exist.
+ */
+export function checkPoolCapacity(opts) {
+    const { pool, accounts } = opts;
+    if (!pool || pool.mode === 'shared' || pool.leaseScope === 'scenario' || !accounts)
+        return [];
+    const out = [];
+    for (const [role, units] of opts.demand) {
+        const have = accounts.get(role) ?? 0;
+        const concurrent = Math.min(opts.workers, units);
+        if (have > 0 && have < concurrent)
+            out.push({ role, accounts: have, concurrent });
+    }
+    return out.sort((a, b) => a.role.localeCompare(b.role));
+}
+/** Accounts per role for the resolved env, after `env.users.poolSize`. Undefined if not file-backed. */
+export function poolAccountsFor(config) {
+    return poolAccountsByEnv(config.project, {
+        envs: [config.env.name],
+        poolSize: () => config.env.users.poolSize,
+    })?.get(config.env.name);
+}
+/** How the worker count was arrived at, for messages. */
+export function describeWorkers(workers) {
+    return workers !== undefined
+        ? `${workers} worker(s)`
+        : `${effectiveWorkers()} worker(s) (Playwright's default: half of ${cpus().length} cores)`;
+}
+export function poolTooSmallError(config, shortfalls, runtimeWorkers) {
+    const pool = config.project.data.userPool;
+    const lines = shortfalls.map((s) => `role "${s.role}" has ${s.accounts} account(s) but ${s.concurrent} of its scenarios can run at once`);
+    return new SdodsError('USER_POOL_TOO_SMALL', `User pool too small for ${describeWorkers(runtimeWorkers)} in env ${config.env.name}: ${lines.join('; ')}. ` +
+        `Leases are held per worker, so every worker past the account count would wait ` +
+        `${pool ? Math.round(leaseWaitMs(pool) / 1000) : 30}s and fail each of those scenarios with USER_POOL_EXHAUSTED.`, {
+        hint: `Any one of: set data.userPool.leaseScope: scenario to release an account when each ` +
+            `scenario ends (scenarios then queue for it); add accounts with ` +
+            `${shortfalls.map((s) => `role "${s.role}"`).join(', ')} to dataset "${pool?.dataset}"` +
+            `${config.env.users.poolSize ? ` (env.users.poolSize ${config.env.users.poolSize} caps the dataset before roles are split)` : ''}; ` +
+            `set data.userPool.mode: shared if these scenarios do not mutate user-scoped state; ` +
+            `run with --workers ${Math.max(1, Math.min(...shortfalls.map((s) => s.accounts)))}; ` +
+            `or pass --allow-pool-contention to run anyway.`,
+        docsPath: '/docs/guides/test-data-and-user-pools',
+        details: { env: config.env.name, shortfalls },
+        exitCode: 2,
+    });
+}
+//# sourceMappingURL=pool-capacity.js.map

package/dist/data/user-pool.d.ts

@@ -1,3 +1,4 @@
+import type { UserPoolConfig } from '@sdods/contracts';
 import type { ResolvedConfig } from '../config/resolve.js';
 import type { DataProvider, LeaseStore, LeasedUser, UserPool } from './types.js';
 /** O_EXCL lock files with TTL; safe across workers on one machine. */
@@ -14,10 +15,37 @@ export interface UserPoolOptions {
     owner: string;
     store?: LeaseStore;
     waitMs?: number;
+    /** Where waiters take their place in line. Default: `.queue` beside the lease files. */
+    queueDir?: string;
 }
+/** `data.userPool.waitMs` when unset and leases are held per worker. */
+export declare const DEFAULT_LEASE_WAIT_MS = 30000;
+/**
+ * The worker count Playwright will actually use: `--workers` / `SDODS_WORKERS` when set (both land
+ * in `runtime.workers`), else Playwright's own default of half the logical cores.
+ *
+ * Every browser and layer of one `sdods run` shares this pool: the CLI starts ONE `playwright test`
+ * with a `--project` per run target, and Playwright's `workers` caps the whole invocation.
+ */
+export declare function effectiveWorkers(workers?: number): number;
+/** How long a lease request waits for a free account (see `data.userPool.waitMs`). */
+export declare function leaseWaitMs(pool: Pick<UserPoolConfig, 'waitMs' | 'leaseScope' | 'leaseTtlMs'>): number;
+/**
+ * With `leaseScope: scenario`, waiting for an account is how one account serialises the scenarios
+ * that need it, so the wait must not count against the scenario's own timeout: a scenario third in
+ * line would otherwise fail having done nothing. The timeout is raised by the longest possible wait
+ * before leasing, then settled to what was actually waited.
+ */
+export declare function scenarioLeaseClock(pool: UserPoolConfig | undefined, testInfo: {
+    timeout: number;
+    setTimeout(ms: number): void;
+}): {
+    settle(): void;
+};
 /**
  * Pool of accounts from the configured dataset, partitioned by role and capped by env.users.poolSize.
- * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown.
+ * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown, or
+ * at scenario teardown with `leaseScope: scenario`.
  */
 export declare class FileUserPool implements UserPool {
     private readonly config;
@@ -26,11 +54,24 @@ export declare class FileUserPool implements UserPool {
     private readonly log;
     private readonly leased;
     private rows?;
-    private readonly store;
+    private storeInstance?;
+    private readonly leaseDir;
     constructor(config: ResolvedConfig, data: DataProvider, opts: UserPoolOptions);
+    /**
+     * Created on first use. Every scenario depends on the pool (the scenario-scope release fixture is
+     * automatic), and a project that never leases must not grow a lease directory for it.
+     */
+    private get store();
     static ownerFor(config: ResolvedConfig, parallelIndex: number): string;
     private users;
     lease(role: string, _parallelIndex: number): Promise<LeasedUser>;
+    /**
+     * A place in line for `role`: an empty file named by arrival time and owner, refreshed while its
+     * waiter polls. `ahead()` counts live tickets that arrived earlier, and a waiter only tries to
+     * acquire while fewer are ahead of it than the role has accounts. A ticket nobody refreshes (its
+     * worker crashed) goes stale and stops holding the line.
+     */
+    private queueTicket;
     release(user: LeasedUser): Promise<void>;
     releaseAll(): Promise<void>;
     status(): Promise<{