@sdods/core 0.7.2 → 0.9.0

package/dist/shots/narrator.d.ts

@@ -25,7 +25,15 @@ export declare class ScreenshotNarrator {
     beforeStep(stepIndex: number, _title?: string): Promise<void>;
     afterStep(stepIndex: number, _title?: string): Promise<void>;
     private stepShot;
-    /** Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)`. */
-    visual(name: string, stepIndex: number): Promise<void>;
+    /**
+     * Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)` with the merged mask
+     * and threshold (see {@link visualCheckOptions}). A failure leaves a {@link VisualFailure} record
+     * and copies of the images in the scenario directory for `sdods baselines` to review and accept.
+     */
+    visual(name: string, stepIndex: number, extraMask?: readonly string[]): Promise<void>;
+    private visualIdentity;
+    private recordVisualPass;
+    /** Never throws: the check's own error is what the scenario reports. */
+    private recordVisualFailure;
 }
 //# sourceMappingURL=narrator.d.ts.map

package/dist/shots/narrator.js

@@ -1,7 +1,9 @@
-import { existsSync } from 'node:fs';
+import { copyFileSync, existsSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
 import { expect } from '@playwright/test';
 import { attachmentNames, scenarioFiles, } from '@sdods/contracts';
 import { Logger } from '../logger.js';
+import { baselineKey, parseVisualError, pngSize, visualCheckOptions } from './baselines.js';
 /** Takes the before/after/scenario screenshots dictated by the policy and attaches them with shared names. */
 export class ScreenshotNarrator {
     deps;
@@ -71,17 +73,36 @@ export class ScreenshotNarrator {
     stepShot(stepIndex, phase) {
         return this.capture(this.deps.scenario.file(scenarioFiles.stepShot(stepIndex, phase)), attachmentNames.shotStep(stepIndex, phase));
     }
-    /** Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)`. */
-    async visual(name, stepIndex) {
+    /**
+     * Visual baseline check (`@visual`): `expect(page).toHaveScreenshot(name)` with the merged mask
+     * and threshold (see {@link visualCheckOptions}). A failure leaves a {@link VisualFailure} record
+     * and copies of the images in the scenario directory for `sdods baselines` to review and accept.
+     */
+    async visual(name, stepIndex, extraMask = []) {
         const { page, policy, testInfo } = this.deps;
         const fileName = name.endsWith('.png') ? name : `${name}.png`;
-        await expect(page).toHaveScreenshot(fileName, {
-            fullPage: policy.fullPage,
-            animations: 'disabled',
-            caret: 'hide',
-            mask: policy.mask.map((sel) => page.locator(sel)),
-            maxDiffPixelRatio: 0.01,
-        });
+        const opts = visualCheckOptions(fileName, policy, extraMask);
+        const hadBaseline = existsSync(testInfo.snapshotPath(fileName));
+        try {
+            await expect(page).toHaveScreenshot(fileName, {
+                fullPage: policy.fullPage,
+                animations: 'disabled',
+                caret: 'hide',
+                mask: opts.mask.map((sel) => page.locator(sel)),
+                maxDiffPixelRatio: opts.maxDiffPixelRatio,
+            });
+        }
+        catch (e) {
+            this.recordVisualFailure(fileName, stepIndex, opts.maxDiffPixelRatio, e);
+            throw e;
+        }
+        // With Playwright's default `updateSnapshots: 'missing'` a missing baseline does not throw: it
+        // writes the actual image as the baseline and fails the test afterwards (a soft error). That is
+        // the first run on a new platform, and exactly the check `sdods baselines` must offer.
+        if (!hadBaseline && testInfo.config.updateSnapshots === 'missing')
+            this.recordVisualFailure(fileName, stepIndex, opts.maxDiffPixelRatio, new Error("A snapshot doesn't exist, writing actual."));
+        else
+            this.recordVisualPass(fileName);
         const snapshot = testInfo.snapshotPath(fileName);
         if (existsSync(snapshot))
             await testInfo.attach(attachmentNames.visual(stepIndex, name), {
@@ -89,6 +110,81 @@ export class ScreenshotNarrator {
                 contentType: 'image/png',
             });
     }
+    visualIdentity(fileName) {
+        const { scenario, testInfo } = this.deps;
+        return {
+            name: baselineKey(fileName),
+            runnerProject: testInfo.project.name,
+            fingerprint: scenario.fingerprint,
+            retry: testInfo.retry,
+        };
+    }
+    recordVisualPass(fileName) {
+        const id = this.visualIdentity(fileName);
+        try {
+            writeFileSync(this.deps.scenario.file(scenarioFiles.visualPassed(id.runnerProject, id.name)), JSON.stringify({ ...id, recordedAt: new Date().toISOString() }));
+        }
+        catch (err) {
+            this.log.debug(`visual pass marker skipped: ${err.message}`);
+        }
+    }
+    /** Never throws: the check's own error is what the scenario reports. */
+    recordVisualFailure(fileName, stepIndex, maxDiffPixelRatio, error) {
+        const { scenario, testInfo } = this.deps;
+        try {
+            const id = this.visualIdentity(fileName);
+            const base = fileName.replace(/\.png$/i, '');
+            // Playwright attaches `<name>-actual.png` etc. and writes them to the test's output dir.
+            const source = (phase) => {
+                const att = testInfo.attachments.find((a) => a.name === `${base}-${phase}.png`)?.path;
+                const p = att ?? testInfo.outputPath(`${base}-${phase}.png`);
+                return existsSync(p) ? p : undefined;
+            };
+            const parsed = parseVisualError(error?.message ?? String(error));
+            const copies = {};
+            for (const phase of ['actual', 'expected', 'diff']) {
+                // A missing baseline's "expected" attachment is the actual image Playwright just wrote.
+                if (phase !== 'actual' && parsed.reason === 'missing')
+                    continue;
+                const src = source(phase);
+                if (!src)
+                    continue;
+                const dest = scenario.file(scenarioFiles.visualImage(id.runnerProject, id.name, phase));
+                copyFileSync(src, dest);
+                copies[phase] = relative(scenario.runDir, dest).split('\\').join('/');
+            }
+            // No actual image means the page could not be captured at all: nothing to accept.
+            if (!copies.actual)
+                return;
+            const size = pngSize(scenario.file(scenarioFiles.visualImage(id.runnerProject, id.name, 'actual')));
+            const record = {
+                ...id,
+                snapshot: fileName,
+                project: scenario.data.project,
+                platform: process.platform,
+                scenarioName: scenario.data.scenarioName,
+                featureUri: scenario.data.featureUri,
+                stepIndex,
+                reason: parsed.reason,
+                baseline: relative(scenario.projectRoot, testInfo.snapshotPath(fileName))
+                    .split('\\')
+                    .join('/'),
+                actual: copies.actual,
+                expected: copies.expected,
+                diff: copies.diff,
+                diffPixels: parsed.diffPixels,
+                diffRatio: parsed.diffPixels !== undefined && size
+                    ? parsed.diffPixels / (size.width * size.height)
+                    : undefined,
+                maxDiffPixelRatio,
+                recordedAt: new Date().toISOString(),
+            };
+            writeFileSync(scenario.file(scenarioFiles.visualFailure(id.runnerProject, id.name)), JSON.stringify(record, null, 2));
+        }
+        catch (err) {
+            this.log.debug(`visual failure record skipped: ${err.message}`);
+        }
+    }
 }
 function safeUrl(page) {
     try {

package/dist/shots/policy.d.ts

@@ -1,9 +1,13 @@
-import type { ShotPolicy } from '@sdods/contracts';
+import type { BaselineConfig, ShotPolicy } from '@sdods/contracts';
 import type { ResolvedConfig } from '../config/resolve.js';
 export interface ShotPolicyResolved {
     mode: ShotPolicy;
     fullPage: boolean;
     mask: string[];
+    /** default share of pixels a visual baseline check may differ by */
+    maxDiffPixelRatio: number;
+    /** per-baseline mask and threshold, keyed by name without `.png` */
+    baselines: Record<string, BaselineConfig>;
     viewport: {
         width: number;
         height: number;

package/dist/shots/policy.js

@@ -24,6 +24,8 @@ export function resolvePolicy(tags, config) {
         mode,
         fullPage: s.fullPage,
         mask: s.mask,
+        maxDiffPixelRatio: s.maxDiffPixelRatio ?? 0.01,
+        baselines: s.baselines ?? {},
         viewport: s.viewport,
         scenario: mode === 'scenario' || mode === 'step' || mode === 'visual',
         step: mode === 'step' || mode === 'visual',

package/dist/steps/a11y.steps.d.ts

@@ -1,57 +1,24 @@
 import './params.js';
+import { type A11yResults } from '../a11y/audit.js';
 /**
- * Structural subset of axe-core's result types. Declared locally rather than imported from
- * `axe-core`: that package is a transitive dependency of `@axe-core/playwright`, not a direct
- * dependency of this one, so importing its types would couple the whole step library's
- * compilation to a package a consumer may not have installed.
- */
-export interface A11yViolationNode {
-    target: unknown[];
-    html?: string;
-    failureSummary?: string;
-}
-export interface A11yViolation {
-    id: string;
-    impact?: string | null;
-    help?: string;
-    helpUrl?: string;
-    nodes: A11yViolationNode[];
-}
-export interface A11yResults {
-    violations: A11yViolation[];
-    passes: {
-        id: string;
-    }[];
-    incomplete: {
-        id: string;
-    }[];
-    inapplicable: {
-        id: string;
-    }[];
-    url?: string;
-}
-/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
-export declare const IMPACT_ORDER: readonly ["minor", "moderate", "serious", "critical"];
-/**
- * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
- * changes between axe releases, so including it would let the same unchanged page pass one week
- * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
- */
-export declare const WCAG_AA_TAGS: string[];
-/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
-export declare function impactRank(impact: string | null | undefined): number;
-/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
-export declare function parseImpactFloor(level: string): number;
-export declare function violationsAtOrAbove(violations: A11yViolation[], floor: number): A11yViolation[];
-/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
-export declare function describeViolations(violations: A11yViolation[]): string;
-/**
- * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
- * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
- * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
- * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ * Accessibility steps: an axe-core audit plus the structural checks a rule engine cannot see.
+ *
+ * DESIGN — the browser gathers, node judges. Every DOM probe below returns plain serialisable
+ * records and nothing else; the pass/fail decision lives in an exported pure function. That split
+ * exists so the one rule that matters here is testable without a browser: a step that quantifies
+ * over a set MUST fail when the set is empty. "Every image has an alt" over a page with no images
+ * and "no violations" inside a region that does not exist are not passes, they are silence, and
+ * silence is what makes an accessibility suite worthless. `assertRegion` and `assertGathered` are
+ * the guards, and they throw rather than assert so the message can say what to do instead.
+ *
+ * WHY NO `heal.*` HERE. The rest of the UI library heals because it resolves ONE interactive
+ * element by role/name/text, and a near-miss substitute is still the control the author meant.
+ * These steps quantify over a POPULATION inside a region: healing a region selector to a
+ * different element would silently re-point the audit at a different set of nodes and report a
+ * green result for a surface nobody asked about. A missing region is a defect in the step, so it
+ * is reported as one.
  */
-export declare function assertAxeChecked(results: A11yResults, where: string): void;
+export { IMPACT_ORDER, WCAG_AA_TAGS, assertAxeChecked, describeViolations, impactRank, parseImpactFloor, violationsAtOrAbove, type A11yResults, type A11yViolation, type A11yViolationNode, } from '../a11y/audit.js';
 export type RuleBucket = 'violations' | 'passes' | 'incomplete' | 'inapplicable' | 'none';
 /** Which of axe's four result buckets a rule landed in. `none` means the rule never ran. */
 export declare function ruleBucket(results: A11yResults, ruleId: string): RuleBucket;

package/dist/steps/a11y.steps.js

@@ -4,6 +4,7 @@ import { attachmentNames, scenarioFiles } from '@sdods/contracts';
 import './params.js';
 import { Then } from '../fixtures/test.js';
 import { renderStrict } from '../api/template.js';
+import { IMPACT_ORDER, assertAxeChecked, describeViolations, markPageAudited, parseImpactFloor, runAxe, violationsAtOrAbove, } from '../a11y/audit.js';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
 /**
@@ -24,63 +25,11 @@ import { Logger } from '../logger.js';
  * green result for a surface nobody asked about. A missing region is a defect in the step, so it
  * is reported as one.
  */
+// The audit and its judges moved to `../a11y/audit.ts` so the `@a11y` tag hook can share them
+// without importing (and so re-registering) this step file. Re-exported for existing importers.
+export { IMPACT_ORDER, WCAG_AA_TAGS, assertAxeChecked, describeViolations, impactRank, parseImpactFloor, violationsAtOrAbove, } from '../a11y/audit.js';
 const log = new Logger('a11y');
 const scopesOf = (apiContext, env) => [apiContext.vars.toObject(), env.vars];
-/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
-export const IMPACT_ORDER = ['minor', 'moderate', 'serious', 'critical'];
-/**
- * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
- * changes between axe releases, so including it would let the same unchanged page pass one week
- * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
- */
-export const WCAG_AA_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
-/* ── pure judges (exported so the vacuity guards are unit-testable) ─────── */
-/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
-export function impactRank(impact) {
-    const i = IMPACT_ORDER.indexOf((impact ?? 'minor'));
-    return i === -1 ? 0 : i;
-}
-/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
-export function parseImpactFloor(level) {
-    const i = IMPACT_ORDER.indexOf(level);
-    if (i === -1)
-        throw new SdodsError('CONFIG_INVALID', `"${level}" is not an axe impact level.`, {
-            hint: `Use one of: ${IMPACT_ORDER.join(', ')}.`,
-        });
-    return i;
-}
-export function violationsAtOrAbove(violations, floor) {
-    return violations.filter((v) => impactRank(v.impact) >= floor);
-}
-/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
-export function describeViolations(violations) {
-    return violations
-        .map((v) => {
-        const nodes = v.nodes ?? [];
-        const shown = nodes
-            .slice(0, 3)
-            .map((n) => (Array.isArray(n.target) ? n.target.join(' ') : String(n.target)))
-            .join(' | ');
-        const more = nodes.length > 3 ? ` (+${nodes.length - 3} more node(s))` : '';
-        return `${v.id} [${v.impact ?? 'minor'}] ${v.help ?? ''} → ${nodes.length} node(s): ${shown}${more}`;
-    })
-        .join('\n');
-}
-/**
- * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
- * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
- * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
- * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
- */
-export function assertAxeChecked(results, where) {
-    const checked = (results.passes?.length ?? 0) +
-        (results.violations?.length ?? 0) +
-        (results.incomplete?.length ?? 0);
-    if (checked === 0)
-        throw new SdodsError('RUN_FAILED', `axe examined nothing ${where}; the audit proves nothing.`, {
-            hint: 'The page may be blank, the scoped selector may match an empty element, or a Content-Security-Policy may have blocked axe from running. Open the attached sdods/a11y JSON to see what axe reported.',
-        });
-}
 /** Which of axe's four result buckets a rule landed in. `none` means the rule never ran. */
 export function ruleBucket(results, ruleId) {
     if (results.violations?.some((r) => r.id === ruleId))
@@ -354,58 +303,6 @@ export const gatherFocusIndicators = (sel) => {
     }
     return { regionFound: true, items: out };
 };
-/**
- * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
- * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
- * silently, and the audit would report zero violations because it never ran.
- *
- * The import is lazy so a project that never writes an a11y step does not need the dependency —
- * a top-level import would fail the load of this whole step file and take the rest of the core
- * library down with it.
- */
-async function runAxe(page, opts) {
-    let AxeBuilder;
-    try {
-        const mod = await import('@axe-core/playwright');
-        // Named export first: the package exports the class as both `AxeBuilder` and `default`, and a
-        // CJS interop path can hand `default` back as the namespace object rather than the class.
-        AxeBuilder = (mod.AxeBuilder ?? mod.default);
-    }
-    catch (cause) {
-        throw new SdodsError('NOT_SUPPORTED', 'Accessibility steps need @axe-core/playwright.', {
-            hint: 'Install it in the project that runs these steps: `npm i -D @axe-core/playwright`.',
-            cause,
-        });
-    }
-    const builder = new AxeBuilder({ page });
-    if (opts.include)
-        builder.include(opts.include);
-    // withTags and withRules are mutually exclusive in axe-core; never set both.
-    if (opts.rules)
-        builder.withRules(opts.rules);
-    else
-        builder.withTags(opts.tags ?? WCAG_AA_TAGS);
-    try {
-        return await builder.analyze();
-    }
-    catch (cause) {
-        // axe raises "unknown rule `x` in options.runOnly" for a rule id that does not exist, and
-        // "No elements found for include in page Context" for a selector that matched nothing. Both
-        // are defects in the step rather than in the page under test, so both are re-raised as such.
-        const message = cause instanceof Error ? cause.message : String(cause);
-        if (/unknown rule/i.test(message))
-            throw new SdodsError('CONFIG_INVALID', `axe rejected the rule id: ${message}`, {
-                hint: 'Check the rule id against https://dequeuniversity.com/rules/axe.',
-                cause,
-            });
-        if (/no elements found for include/i.test(message))
-            throw new SdodsError('RUN_FAILED', `axe found nothing to scan: ${message}`, {
-                hint: `The selector "${opts.include ?? ''}" matched no element by the time axe ran. Wait for the region to render before this step.`,
-                cause,
-            });
-        throw new SdodsError('RUN_FAILED', `axe failed to analyse the page: ${message}`, { cause });
-    }
-}
 /**
  * Writes the full axe result next to the scenario and attaches it under `sdods/a11y/<step>`.
  * Always attached, pass or fail: on a failure it is what makes the verdict diagnosable, and on a
@@ -439,6 +336,7 @@ async function requireRegion(page, selector) {
  */
 Then('the page should have no accessibility violations', async ({ page, scenario, $bddContext, $testInfo }) => {
     const results = await runAxe(page, {});
+    markPageAudited(scenario, page.url());
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     assertAxeChecked(results, `on ${page.url()}`);
     expect(results.violations.length, `${results.violations.length} WCAG A/AA violation(s) on ${page.url()}:\n${describeViolations(results.violations)}`).toBe(0);
@@ -464,6 +362,7 @@ Then('the page should have no accessibility violations within {string}', async (
 Then('the page should have no accessibility violations of impact {string} or worse', async ({ page, scenario, apiContext, env, $bddContext, $testInfo }, level) => {
     const floor = parseImpactFloor(renderStrict(level, ...scopesOf(apiContext, env)));
     const results = await runAxe(page, {});
+    markPageAudited(scenario, page.url());
     attachA11y({ scenario, testInfo: $testInfo, stepIndex: $bddContext.stepIndex }, results);
     assertAxeChecked(results, `on ${page.url()}`);
     const blocking = violationsAtOrAbove(results.violations, floor);

package/dist/steps/api.steps.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import './params.js';
 import { Given, Then, When } from '../fixtures/test.js';
-import { coerce, getPath } from '../api/json-path.js';
+import { coerce, getPath, matchedPath } from '../api/json-path.js';
 import { renderJson, renderStrict } from '../api/template.js';
 import { pollUntil } from '../api/poll.js';
 import { loadJsonSchema, loadZodSchema, validateAgainstOpenApi, validateJsonSchema, validateZod, } from '../api/validate.js';
@@ -104,12 +104,12 @@ Then('the response JSON path {string} should match {string}', async ({ apiContex
 });
 Then('the response JSON path {string} should have {int} items', async ({ apiContext, env }, jsonPath, count) => {
     const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
-    const actual = getPath(apiContext.last().response.body, path);
+    const actual = matchedPath(apiContext.last().response.body, path);
     expect(Array.isArray(actual) ? actual.length : -1, `JSON path ${path} length`).toBe(count);
 });
 Then('the response JSON path {string} should have at least {int} items', async ({ apiContext, env }, jsonPath, count) => {
     const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
-    const actual = getPath(apiContext.last().response.body, path);
+    const actual = matchedPath(apiContext.last().response.body, path);
     expect(Array.isArray(actual) ? actual.length : -1, `JSON path ${path} length`).toBeGreaterThanOrEqual(count);
 });
 Then('the response body should be an array', async ({ apiContext }) => {
@@ -144,10 +144,8 @@ Then('the response should match the OpenAPI schema for {method} {string}', async
 When('I save the response JSON path {string} as {string}', async ({ apiContext, env }, jsonPath, name) => {
     // `name` is the variable being written, an identifier rather than a template.
     const path = renderStrict(jsonPath, apiContext.vars.toObject(), env.vars);
-    const value = getPath(apiContext.last().response.body, path);
-    if (value === undefined)
-        throw new SdodsError('RUN_FAILED', `JSON path ${path} is undefined in the last response; cannot save as {{${name}}}.`);
-    apiContext.vars.set(name, value);
+    // A present `null` or `[]` is saved as is; only a path that matched nothing fails.
+    apiContext.vars.set(name, matchedPath(apiContext.last().response.body, path, `{{${name}}}`));
 });
 Given('I set the variable {string} to {string}', async ({ apiContext, env }, name, value) => {
     apiContext.vars.set(name, coerce(renderStrict(value, apiContext.vars.toObject(), env.vars)));

package/dist/steps/browser.steps.d.ts

@@ -24,4 +24,16 @@ export declare function firstPaintedColour(chain: BackgroundLayer[]): PaintedCol
  * shape of the text gives it away.
  */
 export declare function looksLikeMessageKey(text: string): boolean;
+/**
+ * What counts as an untranslated key in visible text, by default:
+ *   * a whole text node shaped like a catalogue key — `nav.settings`, `checkout.summary.total`
+ *     (the same rule as {@link looksLikeMessageKey}: file names, hostnames and versions excluded);
+ *   * an unrendered interpolation placeholder — `Hello {{name}}`;
+ *   * a library's own missing marker — `[missing "fr.nav.home" translation]` (i18n-js) or
+ *     `translation missing: fr.nav.home` (Rails).
+ * A project whose keys look different passes its own pattern to the `matching {string}` step,
+ * which then replaces these defaults.
+ */
+export declare const UNTRANSLATED_MARKERS: readonly RegExp[];
+export declare function findUntranslated(texts: readonly string[], pattern?: RegExp): string[];
 //# sourceMappingURL=browser.steps.d.ts.map

package/dist/steps/browser.steps.js

@@ -1,6 +1,7 @@
-import { expect } from '@playwright/test';
+import { devices, expect } from '@playwright/test';
 import { Given, Then, When } from '../fixtures/test.js';
 import { renderStrict } from '../api/template.js';
+import { COLOR_SCHEMES, emulationTagProblem, findDevice, parseViewport, } from '../config/emulation.js';
 import { SdodsError } from '../errors.js';
 /**
  * Browser-state steps: cookies, web storage, viewport, colour scheme, locale and console.
@@ -292,11 +293,14 @@ function probeHorizontalOverflow() {
 // TRAP: a blank document also does not scroll sideways. The body-children guard is what stops this
 // step going green on a page that failed to render, which is the one case it must not bless.
 Then('the page should not scroll horizontally', async ({ page }) => {
-    requireNavigated(page, 'the page should not scroll horizontally');
+    await expectNoHorizontalScroll(page, 'the page should not scroll horizontally');
+});
+async function expectNoHorizontalScroll(page, step) {
+    requireNavigated(page, step);
     const report = (await page.evaluate(probeHorizontalOverflow));
     expect(report.bodyChildren, 'the document body is empty — a blank page cannot prove anything about reflow').toBeGreaterThan(0);
     expect(report.scrollWidth, `the document is ${report.scrollWidth}px wide inside a ${report.clientWidth}px viewport. Offenders: ${report.offenders.join(', ') || '(none measurable)'}`).toBeLessThanOrEqual(report.clientWidth + 1);
-});
+}
 // Proves ONE container contains its own width — a table, a code block or a chart that is allowed
 // to scroll internally must not push the page. Fails when the selector matches nothing, because a
 // containment claim about an element that is not on the page is not a claim.
@@ -651,4 +655,151 @@ Then('no uncaught page error should have been recorded', async ({ apiContext })
     const recording = recordingFor(apiContext, 'no uncaught page error should have been recorded');
     expect(recording.pageErrors, 'uncaught page errors').toEqual([]);
 });
+/* ── per-scenario emulation: the `I use …` family (#116) ─────────────── */
+// Locale, timezone and device are browser-CONTEXT options: Playwright fixes them when the context
+// is created and offers no way to change them afterwards. By the time the first step runs, the
+// context is open, so these steps cannot apply a value. The tags `@locale:` `@timezone:` and
+// `@device:` are resolved before the context opens; each step below passes when the context
+// already has the value (it then states the scenario's intent in its text) and otherwise fails,
+// naming the tag to use. Recreating the context was rejected: the page objects, the healer and the
+// screenshot narrator already hold the original page, and would silently act on a closed one.
+// Colour scheme and viewport CAN change on a live page, so those steps apply their value.
+function contextFixed(what, tag, actual) {
+    return new SdodsError('RUN_FAILED', 
+    // The tag is in the MESSAGE, not only the hint: a Playwright report shows the message alone.
+    `The browser context was created with ${what} ${actual === undefined ? '(the system default)' : `"${actual}"`}, and Playwright cannot change it on an open context — tag the scenario ${tag}.`, {
+        hint: `Tag the scenario ${tag} (or its Feature, or an Examples block) — the tag is applied before the context is created, and this step then passes.`,
+    });
+}
+// Proves the scenario runs under this locale: navigator.language, Intl formatting and the
+// Accept-Language header all come from it. Passes only when `@locale:` (or the env's `use.locale`)
+// already set it.
+Given('I use the locale {string}', async ({ locale, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const problem = emulationTagProblem('locale', wanted);
+    if (problem)
+        throw new SdodsError('RUN_FAILED', problem);
+    const canon = (l) => Intl.getCanonicalLocales(l)[0];
+    if (!locale || canon(locale) !== canon(wanted))
+        throw contextFixed('locale', `@locale:${wanted}`, locale);
+});
+// Proves the scenario runs in this IANA time zone — the one that decides what "today" and every
+// rendered timestamp mean. Passes only when `@timezone:` (or `use.timezoneId`) already set it.
+Given('I use the timezone {string}', async ({ timezoneId, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const problem = emulationTagProblem('timezone', wanted);
+    if (problem)
+        throw new SdodsError('RUN_FAILED', problem);
+    if (timezoneId !== wanted)
+        throw contextFixed('time zone', `@timezone:${wanted}`, timezoneId);
+});
+// Proves the OS-level colour preference for the rest of the scenario. Applied on the live page, so
+// it works mid-scenario; `@theme:` does the same before the first paint, which is what a
+// flash-of-wrong-theme check needs.
+Given('I use the {string} color scheme', async ({ page, apiContext, env }, scheme) => {
+    const wanted = renderStrict(scheme, ...scopesOf(apiContext, env));
+    if (!COLOR_SCHEMES.includes(wanted))
+        throw new SdodsError('RUN_FAILED', `"${wanted}" is not a color scheme.`, {
+            hint: `Use one of: ${COLOR_SCHEMES.join(', ')}.`,
+        });
+    await page.emulateMedia({ colorScheme: wanted });
+});
+// Resizes the live page. `@viewport:<W>x<H>` sets the size before the first navigation instead,
+// which matters for apps that choose a layout once, on load.
+Given('I use the viewport {int} by {int}', async ({ page }, width, height) => {
+    const size = parseViewport(`${width}x${height}`);
+    if (!size)
+        throw new SdodsError('RUN_FAILED', `Viewport ${width}x${height} is not a usable size.`, {
+            hint: 'Both dimensions must be positive integers, e.g. `Given I use the viewport 320 by 640`.',
+        });
+    await page.setViewportSize(size);
+});
+// Proves the scenario runs with this device's viewport, user agent, pixel ratio and touch. The
+// engine stays the run target's browser. Passes when the context carries the device's user agent —
+// from `@device:`, or from a mobile run target built on that descriptor (mobile-safari is iPhone 15).
+Given('I use the device {string}', async ({ $sdodsEmulation, userAgent, apiContext, env }, value) => {
+    const wanted = renderStrict(value, ...scopesOf(apiContext, env));
+    const name = findDevice(wanted);
+    if (!name)
+        throw new SdodsError('RUN_FAILED', `"${wanted}" is not a Playwright device.`, {
+            hint: 'Use a descriptor name such as "iPhone 15" or "Pixel 7".',
+        });
+    if ($sdodsEmulation.device?.name !== name && userAgent !== devices[name]?.userAgent)
+        throw contextFixed('device', `@device:${name.replace(/\s+/g, '-')}`, $sdodsEmulation.device?.name ?? 'no device emulation');
+});
+// The WCAG 1.4.10 phrasing of `the page should not scroll horizontally` — same measurement, same
+// blank-page guard. Pair it with `@viewport:320x640`.
+Then('the page should reflow without horizontal scrolling', async ({ page }) => {
+    await expectNoHorizontalScroll(page, 'the page should reflow without horizontal scrolling');
+});
+/**
+ * What counts as an untranslated key in visible text, by default:
+ *   * a whole text node shaped like a catalogue key — `nav.settings`, `checkout.summary.total`
+ *     (the same rule as {@link looksLikeMessageKey}: file names, hostnames and versions excluded);
+ *   * an unrendered interpolation placeholder — `Hello {{name}}`;
+ *   * a library's own missing marker — `[missing "fr.nav.home" translation]` (i18n-js) or
+ *     `translation missing: fr.nav.home` (Rails).
+ * A project whose keys look different passes its own pattern to the `matching {string}` step,
+ * which then replaces these defaults.
+ */
+export const UNTRANSLATED_MARKERS = [
+    /\{\{\s*[^{}\s][^{}]*\}\}/,
+    /\[missing\b[^\]]*\]/i,
+    /\btranslation missing:/i,
+];
+export function findUntranslated(texts, pattern) {
+    const found = new Set();
+    for (const raw of texts) {
+        const text = raw.trim();
+        if (!text)
+            continue;
+        const hit = pattern
+            ? pattern.test(text)
+            : (text.length < 80 && !/\s/.test(text) && looksLikeMessageKey(text)) ||
+                UNTRANSLATED_MARKERS.some((re) => re.test(text));
+        if (hit)
+            found.add(text.length > 120 ? `${text.slice(0, 117)}...` : text);
+    }
+    return [...found];
+}
+/** Every visible text node, whole, plus how many were examined. */
+function collectVisibleTexts() {
+    const skip = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'TITLE'];
+    const texts = [];
+    if (!document.body)
+        return { sampled: 0, texts };
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node) {
+        const parent = node.parentElement;
+        const text = (node.textContent ?? '').trim();
+        if (text && parent && skip.indexOf(parent.tagName) === -1) {
+            const el = parent;
+            const visible = typeof el.checkVisibility === 'function' ? el.checkVisibility() : el.offsetParent !== null;
+            if (visible)
+                texts.push(text);
+        }
+        node = walker.nextNode();
+    }
+    return { sampled: texts.length, texts };
+}
+async function expectNoUntranslated(page, step, pattern) {
+    requireNavigated(page, step);
+    const seen = (await page.evaluate(collectVisibleTexts));
+    // TRAP: a page that rendered no text has no untranslated keys either — fail instead of passing.
+    expect(seen.sampled, 'the page rendered no visible text at all, so this step examined nothing').toBeGreaterThan(0);
+    expect(findUntranslated(seen.texts, pattern), `untranslated keys rendered as visible text${pattern ? ` (matching /${pattern.source}/)` : ''}`).toEqual([]);
+}
+// Proves the catalogue resolved for this locale: no raw key, no unrendered `{{placeholder}}` and
+// no library "missing translation" marker is visible. Run it under each `@locale:`.
+Then('the page should have no untranslated keys', async ({ page }) => {
+    await expectNoUntranslated(page, 'the page should have no untranslated keys');
+});
+// The same check with the project's own definition of an untranslated key (a JavaScript regular
+// expression tested against each visible text node), e.g. "^[A-Z0-9_]{3,}$" for SCREAMING_CASE keys.
+Then('the page should have no untranslated keys matching {string}', async ({ page, apiContext, env }, pattern) => {
+    const step = 'the page should have no untranslated keys matching …';
+    const rendered = renderStrict(pattern, ...scopesOf(apiContext, env));
+    await expectNoUntranslated(page, step, compilePattern(rendered, step));
+});
 //# sourceMappingURL=browser.steps.js.map