@variance-authority/core 0.14.0 → 0.15.0

package/dist/format/drive.d.ts

@@ -0,0 +1,191 @@
+import type { DriverTarget, Intervention } from './intervention.js';
+/**
+ * The tricks a stylesheet cannot reach, and the one call each makes of a driver.
+ *
+ * Every other trick in [`stabilize.ts`](./stabilize.ts) is CSS, a screenshot
+ * option or a script the page runs on itself. Three causes of a page that reads
+ * two ways sit outside the document:
+ *
+ * - **the motion preference** — a page that honours `prefers-reduced-motion`
+ *   runs its script animation only when the browser says motion is welcome, and
+ *   a stylesheet cannot reach a `requestAnimationFrame` loop;
+ * - **the clock** — a page that prints `new Date()` prints a new value every
+ *   run, and the date is read by the page's first script, before any stylesheet
+ *   or settle step exists, so it is replaced by a script the browser runs before
+ *   the page's own;
+ * - **the pointer** — a hover ends when the pointer leaves, and nothing in the
+ *   page can move it.
+ *
+ * So each is declared as a {@link DriverState} and applied here, through the
+ * structural {@link DriverTarget} a Playwright `Page` already is. A host that
+ * owns the browser calls {@link driveBeforeLoad} before its first navigation
+ * and hands the page the ids it applied. A host that shares the page with
+ * somebody who moves the pointer, such as a test, also calls
+ * {@link driveBeforeRead} before each subject is read. A host that does not — a page agent, a test runner's own
+ * browser — drives nothing, and {@link forDriver} keeps those tricks out of its
+ * recorded recipe, so the absence shows in the reading's ids and digest the way
+ * a trick filtered by `needs` does.
+ */
+/**
+ * The instant a fixed clock reads unless a project names another.
+ *
+ * Noon UTC, so it is the same calendar date in every zone from UTC−11 to
+ * UTC+11: a page that prints today's date prints one date whichever zone the
+ * browser runs in. A date in the past, so a page that compares against "now"
+ * to show something as expired does so on every run or on none.
+ */
+export declare const DEFAULT_NOW = "2024-06-15T12:00:00.000Z";
+/**
+ * The milliseconds an ISO 8601 instant names, or an error that says what an
+ * instant is.
+ *
+ * The zone is required. `2024-06-15T12:00` with no zone is read in whatever
+ * zone the machine runs in, so two machines would fix two clocks — the
+ * variance this trick exists to remove.
+ */
+export declare function instantOf(now: string): number;
+/**
+ * `prefers-reduced-motion: reduce`, the switch a well-built page already reads.
+ *
+ * It reaches what `pin-animations` cannot: a script animation, which a
+ * stylesheet has no handle on. It reaches only a page that honours the
+ * preference, and that is the cost: the page is read as a user who asked for
+ * less motion sees it, which can differ from what everybody else sees.
+ */
+export declare const reducedMotion: Intervention;
+/**
+ * `Date` reads one instant; timers, animation frames and `performance` keep
+ * running.
+ *
+ * An init script, {@link freezeDate}, run in every frame before the page's own
+ * first script. It replaces `Date` and nothing else, because the thing that
+ * prints two ways is the date a page shows, and the things that make a page
+ * settle are timers and frames. Playwright's `clock.setFixedTime` was measured
+ * against it and rejected: it installs a fake for `setTimeout`,
+ * `requestAnimationFrame` and `performance.now` as well, and a frame's
+ * timestamp no longer agrees with `document.timeline`, which drives every CSS
+ * and Web Animations frame. Installing no clock also leaves `page.clock` to the
+ * test that wants one.
+ *
+ * The id carries the instant when it is not {@link DEFAULT_NOW}, as
+ * `freeze-clock@2031-01-02T03:04:05.000Z`, so the instant is in the recipe's
+ * digest and so in the environment key: a baseline read at one instant and a
+ * run read at another are compared, and the instant is named as the cause of
+ * whatever changed.
+ *
+ * The cost: code that measures elapsed time with `Date.now()`, such as a
+ * debounce, sees no time pass and never fires. `performance.now()` keeps
+ * counting.
+ */
+export declare function freezeClockAt(now: string): Intervention;
+/** {@link freezeClockAt} the default instant, {@link DEFAULT_NOW}. */
+export declare const freezeClock: Intervention;
+/**
+ * The clock trick a `freeze-clock@<instant>` id names, or undefined for any
+ * other id.
+ *
+ * The registry holds `freeze-clock` alone; an id with an instant in it is
+ * resolved here, so a recipe that crossed into a page as ids keeps its instant.
+ */
+export declare function clockById(id: string): Intervention | undefined;
+/**
+ * The init script {@link freezeClock} installs: `Date` answers `frozen`, and
+ * nothing else changes.
+ *
+ * Runs in the page, so it closes over nothing. `new Date()`, `Date()` and
+ * `Date.now()` read the instant; `new Date(value)`, `Date.UTC`, `Date.parse`
+ * and every method on a date are the browser's own. `Intl.DateTimeFormat`'s
+ * `format()` and `formatToParts()` with no date read the browser's clock rather
+ * than `Date`, so they are given the instant too.
+ */
+export declare function freezeDate(frozen: number): void;
+/**
+ * The pointer moved off the page, so nothing is hovered.
+ *
+ * To `(-1, -1)` rather than to the page's corner: content at the top left is
+ * under `(0, 0)` and stays hovered there. `pointer-events: none` is not a
+ * substitute — measured, an element already hovered keeps `:hover` under it.
+ *
+ * Once per page, before load, where nothing but the host moves the pointer. A
+ * move is acknowledged on the next frame, ~14 ms measured, so a host that alone
+ * drives its page does not move it again. A host that shares the page with a
+ * test does, before every reading: see {@link driveBeforeRead}.
+ */
+export declare const noHover: Intervention;
+/**
+ * Nothing focused, so a field a test filled or a page focused on load reads
+ * as it does untouched.
+ *
+ * A settle step rather than a stylesheet: `:focus` and `:focus-visible` follow
+ * the element that holds focus, and no rule can unmatch them. It blurs the
+ * deepest focused element, walking through shadow roots, because a shadow host
+ * is the document's `activeElement` for whatever its tree focused, and blurring
+ * the host leaves the input inside it focused and outlined.
+ *
+ * The cost: a page evaluate per subject, and an animation frame as well when
+ * the document holds an `[autofocus]`. A host that reads a page somebody goes
+ * on using — a test, an agent's browser — gives focus back once the reading
+ * is taken; a host that owns its page does not need to.
+ */
+export declare const noFocus: Intervention;
+/**
+ * The tricks that put a page into the state nobody is touching, in every
+ * default collection recipe whose tier can see them.
+ *
+ * A hover, a focus, a script animation and a printed date are each a second
+ * reading of one subject, and each comes from something other than the code
+ * under review. Three of them reach the page only through a driver, so a host
+ * that cannot drive one leaves it out of the ids it records — see {@link forDriver}.
+ */
+export declare const UNTOUCHED: readonly Intervention[];
+/**
+ * The media features a recipe's driver tricks make the browser report, merged
+ * under the ones a project declared, or undefined when there are none.
+ *
+ * Collection resolves `@media` against declared features, not against the
+ * browser, so a preference the driver emulated and nobody declared would be
+ * read as unknown: both the `reduce` and the `no-preference` block applied, a
+ * box the browser never drew. Declaring what the trick emulates gives the
+ * preference one owner. A project's own value wins, and
+ * {@link driveBeforeLoad} emulates that value, so the two still agree.
+ */
+export declare function featuresOf(recipe: readonly Intervention[], declared?: Readonly<Record<string, string>>): Readonly<Record<string, string>> | undefined;
+/**
+ * Apply what a recipe asks of the browser before the page loads.
+ *
+ * All three survive navigation, so a host calls this once per page, before its
+ * first `goto` or `setContent`. Returns the ids applied, in recipe order. The
+ * clock's instant is the trick's own, so a host that wants another instant
+ * asks `recipeToDrive` for the recipe rather than telling this.
+ *
+ * `declared` is the media features the project declared. A declared
+ * `prefers-reduced-motion` is what the motion trick emulates, so the browser
+ * reports what the record says; see {@link featuresOf}.
+ */
+export declare function driveBeforeLoad(recipe: readonly Intervention[], target: DriverTarget, declared?: Readonly<Record<string, string>>): Promise<readonly string[]>;
+/**
+ * Take the pointer off the page again before a subject is read.
+ *
+ * For a host that shares the page: a test hovers a menu to open it and then
+ * observes, so the pointer is wherever the test's last step left it. A host
+ * that alone drives its page needs only {@link driveBeforeLoad}.
+ *
+ * Every reading pays the frame, hovered or not: measured in Chromium, a
+ * Playwright hover restyles the element while `:hover` matches nothing from
+ * script, so the page cannot say whether the move is needed. The pointer is
+ * not put back afterwards, and the move fires `mouseleave`: a menu a script
+ * opened on hover is closed for the test's next step.
+ */
+export declare function driveBeforeRead(recipe: readonly Intervention[], target: Pick<DriverTarget, 'mouse'>): Promise<readonly string[]>;
+/**
+ * The recipe as it holds on a page, given the driver tricks a host applied.
+ *
+ * A trick with no `driver` is kept. A trick with one is kept only when its id
+ * is in `driven`: a host that could not drive it leaves it out of the ids and
+ * the digest it records, rather than claiming a hold the page never had. The
+ * clock is the one trick whose id the driver may change, because the instant is
+ * the host's to choose: the recipe's clock is recorded as the one the host
+ * fixed.
+ */
+export declare function forDriver(recipe: readonly Intervention[], driven: readonly string[]): readonly Intervention[];
+//# sourceMappingURL=drive.d.ts.map

package/dist/format/drive.js

@@ -0,0 +1,343 @@
+/**
+ * The tricks a stylesheet cannot reach, and the one call each makes of a driver.
+ *
+ * Every other trick in [`stabilize.ts`](./stabilize.ts) is CSS, a screenshot
+ * option or a script the page runs on itself. Three causes of a page that reads
+ * two ways sit outside the document:
+ *
+ * - **the motion preference** — a page that honours `prefers-reduced-motion`
+ *   runs its script animation only when the browser says motion is welcome, and
+ *   a stylesheet cannot reach a `requestAnimationFrame` loop;
+ * - **the clock** — a page that prints `new Date()` prints a new value every
+ *   run, and the date is read by the page's first script, before any stylesheet
+ *   or settle step exists, so it is replaced by a script the browser runs before
+ *   the page's own;
+ * - **the pointer** — a hover ends when the pointer leaves, and nothing in the
+ *   page can move it.
+ *
+ * So each is declared as a {@link DriverState} and applied here, through the
+ * structural {@link DriverTarget} a Playwright `Page` already is. A host that
+ * owns the browser calls {@link driveBeforeLoad} before its first navigation
+ * and hands the page the ids it applied. A host that shares the page with
+ * somebody who moves the pointer, such as a test, also calls
+ * {@link driveBeforeRead} before each subject is read. A host that does not — a page agent, a test runner's own
+ * browser — drives nothing, and {@link forDriver} keeps those tricks out of its
+ * recorded recipe, so the absence shows in the reading's ids and digest the way
+ * a trick filtered by `needs` does.
+ */
+/**
+ * The instant a fixed clock reads unless a project names another.
+ *
+ * Noon UTC, so it is the same calendar date in every zone from UTC−11 to
+ * UTC+11: a page that prints today's date prints one date whichever zone the
+ * browser runs in. A date in the past, so a page that compares against "now"
+ * to show something as expired does so on every run or on none.
+ */
+export const DEFAULT_NOW = '2024-06-15T12:00:00.000Z';
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * The milliseconds an ISO 8601 instant names, or an error that says what an
+ * instant is.
+ *
+ * The zone is required. `2024-06-15T12:00` with no zone is read in whatever
+ * zone the machine runs in, so two machines would fix two clocks — the
+ * variance this trick exists to remove.
+ */
+export function instantOf(now) {
+    const time = INSTANT.test(now) ? Date.parse(now) : Number.NaN;
+    if (Number.isNaN(time)) {
+        throw new Error('`now` must be an ISO 8601 instant with its zone, such as "2024-06-15T12:00:00Z" or ' +
+            `"2024-06-15T14:00:00+02:00", not ${JSON.stringify(now)}`);
+    }
+    return time;
+}
+/**
+ * `prefers-reduced-motion: reduce`, the switch a well-built page already reads.
+ *
+ * It reaches what `pin-animations` cannot: a script animation, which a
+ * stylesheet has no handle on. It reaches only a page that honours the
+ * preference, and that is the cost: the page is read as a user who asked for
+ * less motion sees it, which can differ from what everybody else sees.
+ */
+export const reducedMotion = {
+    id: 'reduced-motion',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'motion-preference',
+    because: 'the browser reports prefers-reduced-motion: reduce, so a page that honours it stops its script animations',
+    driver: { reducedMotion: 'reduce' },
+};
+const CLOCK_ID = 'freeze-clock';
+/**
+ * `Date` reads one instant; timers, animation frames and `performance` keep
+ * running.
+ *
+ * An init script, {@link freezeDate}, run in every frame before the page's own
+ * first script. It replaces `Date` and nothing else, because the thing that
+ * prints two ways is the date a page shows, and the things that make a page
+ * settle are timers and frames. Playwright's `clock.setFixedTime` was measured
+ * against it and rejected: it installs a fake for `setTimeout`,
+ * `requestAnimationFrame` and `performance.now` as well, and a frame's
+ * timestamp no longer agrees with `document.timeline`, which drives every CSS
+ * and Web Animations frame. Installing no clock also leaves `page.clock` to the
+ * test that wants one.
+ *
+ * The id carries the instant when it is not {@link DEFAULT_NOW}, as
+ * `freeze-clock@2031-01-02T03:04:05.000Z`, so the instant is in the recipe's
+ * digest and so in the environment key: a baseline read at one instant and a
+ * run read at another are compared, and the instant is named as the cause of
+ * whatever changed.
+ *
+ * The cost: code that measures elapsed time with `Date.now()`, such as a
+ * debounce, sees no time pass and never fires. `performance.now()` keeps
+ * counting.
+ */
+export function freezeClockAt(now) {
+    const at = instantOf(now);
+    return {
+        id: at === instantOf(DEFAULT_NOW) ? CLOCK_ID : `${CLOCK_ID}@${new Date(at).toISOString()}`,
+        trick: 'hold',
+        needs: 'layout',
+        governs: 'clock',
+        because: 'Date reads one fixed instant, so elapsed time measured with Date.now() reads zero',
+        driver: { clock: { at } },
+    };
+}
+/** {@link freezeClockAt} the default instant, {@link DEFAULT_NOW}. */
+export const freezeClock = freezeClockAt(DEFAULT_NOW);
+/**
+ * The clock trick a `freeze-clock@<instant>` id names, or undefined for any
+ * other id.
+ *
+ * The registry holds `freeze-clock` alone; an id with an instant in it is
+ * resolved here, so a recipe that crossed into a page as ids keeps its instant.
+ */
+export function clockById(id) {
+    return id.startsWith(`${CLOCK_ID}@`) ? freezeClockAt(id.slice(CLOCK_ID.length + 1)) : undefined;
+}
+/**
+ * The init script {@link freezeClock} installs: `Date` answers `frozen`, and
+ * nothing else changes.
+ *
+ * Runs in the page, so it closes over nothing. `new Date()`, `Date()` and
+ * `Date.now()` read the instant; `new Date(value)`, `Date.UTC`, `Date.parse`
+ * and every method on a date are the browser's own. `Intl.DateTimeFormat`'s
+ * `format()` and `formatToParts()` with no date read the browser's clock rather
+ * than `Date`, so they are given the instant too.
+ */
+export function freezeDate(frozen) {
+    // TODO: `Temporal.Now` and a worker's `Date` read the real clock. This runs
+    // in each frame's window and replaces `Date` alone, so a page that prints a
+    // date from either prints a second reading.
+    const Real = Date;
+    function Frozen(...args) {
+        if (new.target === undefined)
+            return new Real(frozen).toString();
+        return Reflect.construct(Real, args.length === 0 ? [frozen] : args, new.target);
+    }
+    Object.setPrototypeOf(Frozen, Real);
+    Object.defineProperties(Frozen, {
+        prototype: { value: Real.prototype },
+        name: { value: 'Date' },
+        length: { value: 7 },
+        now: { value: () => frozen, writable: true, configurable: true },
+    });
+    Object.defineProperty(Real.prototype, 'constructor', { value: Frozen, writable: true, configurable: true });
+    Object.defineProperty(globalThis, 'Date', { value: Frozen, writable: true, configurable: true });
+    const format = Intl.DateTimeFormat.prototype;
+    const formatting = Object.getOwnPropertyDescriptor(format, 'format')?.get;
+    if (formatting !== undefined) {
+        Object.defineProperty(format, 'format', {
+            configurable: true,
+            get() {
+                const bound = formatting.call(this);
+                return (date) => bound(date === undefined ? frozen : date);
+            },
+        });
+    }
+    const toParts = format.formatToParts;
+    Object.defineProperty(format, 'formatToParts', {
+        configurable: true,
+        writable: true,
+        value(date) {
+            return toParts.call(this, date === undefined ? frozen : date);
+        },
+    });
+}
+/**
+ * The pointer moved off the page, so nothing is hovered.
+ *
+ * To `(-1, -1)` rather than to the page's corner: content at the top left is
+ * under `(0, 0)` and stays hovered there. `pointer-events: none` is not a
+ * substitute — measured, an element already hovered keeps `:hover` under it.
+ *
+ * Once per page, before load, where nothing but the host moves the pointer. A
+ * move is acknowledged on the next frame, ~14 ms measured, so a host that alone
+ * drives its page does not move it again. A host that shares the page with a
+ * test does, before every reading: see {@link driveBeforeRead}.
+ */
+export const noHover = {
+    id: 'no-hover',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'pointer',
+    because: 'the pointer moved off the page, so a hover a test left behind is not read',
+    driver: { pointer: 'outside' },
+};
+/**
+ * Nothing focused, so a field a test filled or a page focused on load reads
+ * as it does untouched.
+ *
+ * A settle step rather than a stylesheet: `:focus` and `:focus-visible` follow
+ * the element that holds focus, and no rule can unmatch them. It blurs the
+ * deepest focused element, walking through shadow roots, because a shadow host
+ * is the document's `activeElement` for whatever its tree focused, and blurring
+ * the host leaves the input inside it focused and outlined.
+ *
+ * The cost: a page evaluate per subject, and an animation frame as well when
+ * the document holds an `[autofocus]`. A host that reads a page somebody goes
+ * on using — a test, an agent's browser — gives focus back once the reading
+ * is taken; a host that owns its page does not need to.
+ */
+export const noFocus = {
+    id: 'no-focus',
+    trick: 'reset',
+    needs: 'layout',
+    governs: 'focus',
+    because: 'focus released, so a field a test or the page focused is read unfocused',
+    // Again in a frame callback when the document holds an `autofocus`, because
+    // the browser honours one at the page's next rendering update: a blur before
+    // it is undone, and a document written by `setContent` has had no update yet.
+    // Only then, so a page without one pays no frame per subject.
+    settle: async (target) => {
+        await target.evaluate(() => new Promise((resolve) => {
+            const view = globalThis;
+            const release = () => {
+                let focused = view.document.activeElement;
+                while (focused?.shadowRoot?.activeElement != null)
+                    focused = focused.shadowRoot.activeElement;
+                focused?.blur?.();
+            };
+            release();
+            if (view.document.querySelector('[autofocus]') === null)
+                return resolve();
+            view.requestAnimationFrame(() => {
+                release();
+                resolve();
+            });
+        }));
+    },
+};
+/**
+ * The tricks that put a page into the state nobody is touching, in every
+ * default collection recipe whose tier can see them.
+ *
+ * A hover, a focus, a script animation and a printed date are each a second
+ * reading of one subject, and each comes from something other than the code
+ * under review. Three of them reach the page only through a driver, so a host
+ * that cannot drive one leaves it out of the ids it records — see {@link forDriver}.
+ */
+export const UNTOUCHED = [noHover, noFocus, reducedMotion, freezeClock];
+const MOTION = 'prefers-reduced-motion';
+/**
+ * The media features a recipe's driver tricks make the browser report, merged
+ * under the ones a project declared, or undefined when there are none.
+ *
+ * Collection resolves `@media` against declared features, not against the
+ * browser, so a preference the driver emulated and nobody declared would be
+ * read as unknown: both the `reduce` and the `no-preference` block applied, a
+ * box the browser never drew. Declaring what the trick emulates gives the
+ * preference one owner. A project's own value wins, and
+ * {@link driveBeforeLoad} emulates that value, so the two still agree.
+ */
+export function featuresOf(recipe, declared) {
+    const motion = recipe.find((intervention) => intervention.driver?.reducedMotion !== undefined);
+    const features = {
+        ...(motion === undefined ? {} : { [MOTION]: motion.driver.reducedMotion }),
+        ...declared,
+    };
+    return Object.keys(features).length === 0 ? undefined : features;
+}
+/**
+ * Apply what a recipe asks of the browser before the page loads.
+ *
+ * All three survive navigation, so a host calls this once per page, before its
+ * first `goto` or `setContent`. Returns the ids applied, in recipe order. The
+ * clock's instant is the trick's own, so a host that wants another instant
+ * asks `recipeToDrive` for the recipe rather than telling this.
+ *
+ * `declared` is the media features the project declared. A declared
+ * `prefers-reduced-motion` is what the motion trick emulates, so the browser
+ * reports what the record says; see {@link featuresOf}.
+ */
+export async function driveBeforeLoad(recipe, target, declared) {
+    const applied = [];
+    for (const intervention of recipe) {
+        const driver = intervention.driver;
+        if (driver?.pointer === 'outside') {
+            await target.mouse.move(-1, -1);
+            applied.push(intervention.id);
+        }
+        else if (driver?.reducedMotion !== undefined) {
+            const preference = motionOf(declared?.[MOTION] ?? driver.reducedMotion);
+            await target.emulateMedia({ reducedMotion: preference });
+            // A declared `no-preference` is emulated and recorded among the features;
+            // the trick's id would claim a reduced motion the page never had.
+            if (preference === driver.reducedMotion)
+                applied.push(intervention.id);
+        }
+        else if (driver?.clock !== undefined) {
+            await target.addInitScript(freezeDate, driver.clock.at);
+            applied.push(intervention.id);
+        }
+    }
+    return applied;
+}
+function motionOf(value) {
+    if (value === 'reduce' || value === 'no-preference')
+        return value;
+    throw new Error(`\`${MOTION}\` is declared as ${JSON.stringify(value)}, which no browser reports; ` +
+        'declare "reduce" or "no-preference"');
+}
+/**
+ * Take the pointer off the page again before a subject is read.
+ *
+ * For a host that shares the page: a test hovers a menu to open it and then
+ * observes, so the pointer is wherever the test's last step left it. A host
+ * that alone drives its page needs only {@link driveBeforeLoad}.
+ *
+ * Every reading pays the frame, hovered or not: measured in Chromium, a
+ * Playwright hover restyles the element while `:hover` matches nothing from
+ * script, so the page cannot say whether the move is needed. The pointer is
+ * not put back afterwards, and the move fires `mouseleave`: a menu a script
+ * opened on hover is closed for the test's next step.
+ */
+export async function driveBeforeRead(recipe, target) {
+    const applied = [];
+    for (const intervention of recipe) {
+        if (intervention.driver?.pointer === 'outside') {
+            await target.mouse.move(-1, -1);
+            applied.push(intervention.id);
+        }
+    }
+    return applied;
+}
+/**
+ * The recipe as it holds on a page, given the driver tricks a host applied.
+ *
+ * A trick with no `driver` is kept. A trick with one is kept only when its id
+ * is in `driven`: a host that could not drive it leaves it out of the ids and
+ * the digest it records, rather than claiming a hold the page never had. The
+ * clock is the one trick whose id the driver may change, because the instant is
+ * the host's to choose: the recipe's clock is recorded as the one the host
+ * fixed.
+ */
+export function forDriver(recipe, driven) {
+    const fixed = driven.map((id) => (id === freezeClock.id ? freezeClock : clockById(id))).find(Boolean);
+    return recipe.flatMap((intervention) => {
+        if (intervention.driver === undefined || driven.includes(intervention.id))
+            return [intervention];
+        return intervention.driver.clock !== undefined && fixed !== undefined ? [fixed] : [];
+    });
+}
+//# sourceMappingURL=drive.js.map

package/dist/format/drive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drive.js","sourceRoot":"","sources":["../../src/format/drive.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DriverTarget,\n  Intervention,\n  MotionPreference,\n  PageFocusable,\n  PageGlobals,\n} from './intervention.js';\n\n/**\n * The tricks a stylesheet cannot reach, and the one call each makes of a driver.\n *\n * Every other trick in [`stabilize.ts`](./stabilize.ts) is CSS, a screenshot\n * option or a script the page runs on itself. Three causes of a page that reads\n * two ways sit outside the document:\n *\n * - **the motion preference** — a page that honours `prefers-reduced-motion`\n *   runs its script animation only when the browser says motion is welcome, and\n *   a stylesheet cannot reach a `requestAnimationFrame` loop;\n * - **the clock** — a page that prints `new Date()` prints a new value every\n *   run, and the date is read by the page's first script, before any stylesheet\n *   or settle step exists, so it is replaced by a script the browser runs before\n *   the page's own;\n * - **the pointer** — a hover ends when the pointer leaves, and nothing in the\n *   page can move it.\n *\n * So each is declared as a {@link DriverState} and applied here, through the\n * structural {@link DriverTarget} a Playwright `Page` already is. A host that\n * owns the browser calls {@link driveBeforeLoad} before its first navigation\n * and hands the page the ids it applied. A host that shares the page with\n * somebody who moves the pointer, such as a test, also calls\n * {@link driveBeforeRead} before each subject is read. A host that does not — a page agent, a test runner's own\n * browser — drives nothing, and {@link forDriver} keeps those tricks out of its\n * recorded recipe, so the absence shows in the reading's ids and digest the way\n * a trick filtered by `needs` does.\n */\n\n/**\n * The instant a fixed clock reads unless a project names another.\n *\n * Noon UTC, so it is the same calendar date in every zone from UTC−11 to\n * UTC+11: a page that prints today's date prints one date whichever zone the\n * browser runs in. A date in the past, so a page that compares against \"now\"\n * to show something as expired does so on every run or on none.\n */\nexport const DEFAULT_NOW = '2024-06-15T12:00:00.000Z';\n\nconst INSTANT = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2})$/;\n\n/**\n * The milliseconds an ISO 8601 instant names, or an error that says what an\n * instant is.\n *\n * The zone is required. `2024-06-15T12:00` with no zone is read in whatever\n * zone the machine runs in, so two machines would fix two clocks — the\n * variance this trick exists to remove.\n */\nexport function instantOf(now: string): number {\n  const time = INSTANT.test(now) ? Date.parse(now) : Number.NaN;\n  if (Number.isNaN(time)) {\n    throw new Error(\n      '`now` must be an ISO 8601 instant with its zone, such as \"2024-06-15T12:00:00Z\" or ' +\n        `\"2024-06-15T14:00:00+02:00\", not ${JSON.stringify(now)}`,\n    );\n  }\n  return time;\n}\n\n/**\n * `prefers-reduced-motion: reduce`, the switch a well-built page already reads.\n *\n * It reaches what `pin-animations` cannot: a script animation, which a\n * stylesheet has no handle on. It reaches only a page that honours the\n * preference, and that is the cost: the page is read as a user who asked for\n * less motion sees it, which can differ from what everybody else sees.\n */\nexport const reducedMotion: Intervention = {\n  id: 'reduced-motion',\n  trick: 'reset',\n  needs: 'layout',\n  governs: 'motion-preference',\n  because: 'the browser reports prefers-reduced-motion: reduce, so a page that honours it stops its script animations',\n  driver: { reducedMotion: 'reduce' },\n};\n\nconst CLOCK_ID = 'freeze-clock';\n\n/**\n * `Date` reads one instant; timers, animation frames and `performance` keep\n * running.\n *\n * An init script, {@link freezeDate}, run in every frame before the page's own\n * first script. It replaces `Date` and nothing else, because the thing that\n * prints two ways is the date a page shows, and the things that make a page\n * settle are timers and frames. Playwright's `clock.setFixedTime` was measured\n * against it and rejected: it installs a fake for `setTimeout`,\n * `requestAnimationFrame` and `performance.now` as well, and a frame's\n * timestamp no longer agrees with `document.timeline`, which drives every CSS\n * and Web Animations frame. Installing no clock also leaves `page.clock` to the\n * test that wants one.\n *\n * The id carries the instant when it is not {@link DEFAULT_NOW}, as\n * `freeze-clock@2031-01-02T03:04:05.000Z`, so the instant is in the recipe's\n * digest and so in the environment key: a baseline read at one instant and a\n * run read at another are compared, and the instant is named as the cause of\n * whatever changed.\n *\n * The cost: code that measures elapsed time with `Date.now()`, such as a\n * debounce, sees no time pass and never fires. `performance.now()` keeps\n * counting.\n */\nexport function freezeClockAt(now: string): Intervention {\n  const at = instantOf(now);\n  return {\n    id: at === instantOf(DEFAULT_NOW) ? CLOCK_ID : `${CLOCK_ID}@${new Date(at).toISOString()}`,\n    trick: 'hold',\n    needs: 'layout',\n    governs: 'clock',\n    because: 'Date reads one fixed instant, so elapsed time measured with Date.now() reads zero',\n    driver: { clock: { at } },\n  };\n}\n\n/** {@link freezeClockAt} the default instant, {@link DEFAULT_NOW}. */\nexport const freezeClock: Intervention = freezeClockAt(DEFAULT_NOW);\n\n/**\n * The clock trick a `freeze-clock@<instant>` id names, or undefined for any\n * other id.\n *\n * The registry holds `freeze-clock` alone; an id with an instant in it is\n * resolved here, so a recipe that crossed into a page as ids keeps its instant.\n */\nexport function clockById(id: string): Intervention | undefined {\n  return id.startsWith(`${CLOCK_ID}@`) ? freezeClockAt(id.slice(CLOCK_ID.length + 1)) : undefined;\n}\n\n/**\n * The init script {@link freezeClock} installs: `Date` answers `frozen`, and\n * nothing else changes.\n *\n * Runs in the page, so it closes over nothing. `new Date()`, `Date()` and\n * `Date.now()` read the instant; `new Date(value)`, `Date.UTC`, `Date.parse`\n * and every method on a date are the browser's own. `Intl.DateTimeFormat`'s\n * `format()` and `formatToParts()` with no date read the browser's clock rather\n * than `Date`, so they are given the instant too.\n */\nexport function freezeDate(frozen: number): void {\n  // TODO: `Temporal.Now` and a worker's `Date` read the real clock. This runs\n  // in each frame's window and replaces `Date` alone, so a page that prints a\n  // date from either prints a second reading.\n  const Real = Date;\n  function Frozen(...args: unknown[]): unknown {\n    if (new.target === undefined) return new Real(frozen).toString();\n    return Reflect.construct(Real, args.length === 0 ? [frozen] : args, new.target);\n  }\n  Object.setPrototypeOf(Frozen, Real);\n  Object.defineProperties(Frozen, {\n    prototype: { value: Real.prototype },\n    name: { value: 'Date' },\n    length: { value: 7 },\n    now: { value: () => frozen, writable: true, configurable: true },\n  });\n  Object.defineProperty(Real.prototype, 'constructor', { value: Frozen, writable: true, configurable: true });\n  Object.defineProperty(globalThis, 'Date', { value: Frozen, writable: true, configurable: true });\n\n  const format = Intl.DateTimeFormat.prototype;\n  const formatting = Object.getOwnPropertyDescriptor(format, 'format')?.get;\n  if (formatting !== undefined) {\n    Object.defineProperty(format, 'format', {\n      configurable: true,\n      get(this: Intl.DateTimeFormat) {\n        const bound = formatting.call(this) as (date?: Date | number) => string;\n        return (date?: Date | number) => bound(date === undefined ? frozen : date);\n      },\n    });\n  }\n  const toParts = format.formatToParts;\n  Object.defineProperty(format, 'formatToParts', {\n    configurable: true,\n    writable: true,\n    value(this: Intl.DateTimeFormat, date?: Date | number) {\n      return toParts.call(this, date === undefined ? frozen : date);\n    },\n  });\n}\n\n/**\n * The pointer moved off the page, so nothing is hovered.\n *\n * To `(-1, -1)` rather than to the page's corner: content at the top left is\n * under `(0, 0)` and stays hovered there. `pointer-events: none` is not a\n * substitute — measured, an element already hovered keeps `:hover` under it.\n *\n * Once per page, before load, where nothing but the host moves the pointer. A\n * move is acknowledged on the next frame, ~14 ms measured, so a host that alone\n * drives its page does not move it again. A host that shares the page with a\n * test does, before every reading: see {@link driveBeforeRead}.\n */\nexport const noHover: Intervention = {\n  id: 'no-hover',\n  trick: 'reset',\n  needs: 'layout',\n  governs: 'pointer',\n  because: 'the pointer moved off the page, so a hover a test left behind is not read',\n  driver: { pointer: 'outside' },\n};\n\n/**\n * Nothing focused, so a field a test filled or a page focused on load reads\n * as it does untouched.\n *\n * A settle step rather than a stylesheet: `:focus` and `:focus-visible` follow\n * the element that holds focus, and no rule can unmatch them. It blurs the\n * deepest focused element, walking through shadow roots, because a shadow host\n * is the document's `activeElement` for whatever its tree focused, and blurring\n * the host leaves the input inside it focused and outlined.\n *\n * The cost: a page evaluate per subject, and an animation frame as well when\n * the document holds an `[autofocus]`. A host that reads a page somebody goes\n * on using — a test, an agent's browser — gives focus back once the reading\n * is taken; a host that owns its page does not need to.\n */\nexport const noFocus: Intervention = {\n  id: 'no-focus',\n  trick: 'reset',\n  needs: 'layout',\n  governs: 'focus',\n  because: 'focus released, so a field a test or the page focused is read unfocused',\n  // Again in a frame callback when the document holds an `autofocus`, because\n  // the browser honours one at the page's next rendering update: a blur before\n  // it is undone, and a document written by `setContent` has had no update yet.\n  // Only then, so a page without one pays no frame per subject.\n  settle: async (target) => {\n    await target.evaluate(\n      () =>\n        new Promise<void>((resolve) => {\n          const view = globalThis as unknown as PageGlobals;\n          const release = (): void => {\n            let focused: PageFocusable | null | undefined = view.document.activeElement;\n            while (focused?.shadowRoot?.activeElement != null) focused = focused.shadowRoot.activeElement;\n            focused?.blur?.();\n          };\n          release();\n          if (view.document.querySelector('[autofocus]') === null) return resolve();\n          view.requestAnimationFrame(() => {\n            release();\n            resolve();\n          });\n        }),\n    );\n  },\n};\n\n/**\n * The tricks that put a page into the state nobody is touching, in every\n * default collection recipe whose tier can see them.\n *\n * A hover, a focus, a script animation and a printed date are each a second\n * reading of one subject, and each comes from something other than the code\n * under review. Three of them reach the page only through a driver, so a host\n * that cannot drive one leaves it out of the ids it records — see {@link forDriver}.\n */\nexport const UNTOUCHED: readonly Intervention[] = [noHover, noFocus, reducedMotion, freezeClock];\n\nconst MOTION = 'prefers-reduced-motion';\n\n/**\n * The media features a recipe's driver tricks make the browser report, merged\n * under the ones a project declared, or undefined when there are none.\n *\n * Collection resolves `@media` against declared features, not against the\n * browser, so a preference the driver emulated and nobody declared would be\n * read as unknown: both the `reduce` and the `no-preference` block applied, a\n * box the browser never drew. Declaring what the trick emulates gives the\n * preference one owner. A project's own value wins, and\n * {@link driveBeforeLoad} emulates that value, so the two still agree.\n */\nexport function featuresOf(\n  recipe: readonly Intervention[],\n  declared?: Readonly<Record<string, string>>,\n): Readonly<Record<string, string>> | undefined {\n  const motion = recipe.find((intervention) => intervention.driver?.reducedMotion !== undefined);\n  const features = {\n    ...(motion === undefined ? {} : { [MOTION]: motion.driver!.reducedMotion! }),\n    ...declared,\n  };\n  return Object.keys(features).length === 0 ? undefined : features;\n}\n\n/**\n * Apply what a recipe asks of the browser before the page loads.\n *\n * All three survive navigation, so a host calls this once per page, before its\n * first `goto` or `setContent`. Returns the ids applied, in recipe order. The\n * clock's instant is the trick's own, so a host that wants another instant\n * asks `recipeToDrive` for the recipe rather than telling this.\n *\n * `declared` is the media features the project declared. A declared\n * `prefers-reduced-motion` is what the motion trick emulates, so the browser\n * reports what the record says; see {@link featuresOf}.\n */\nexport async function driveBeforeLoad(\n  recipe: readonly Intervention[],\n  target: DriverTarget,\n  declared?: Readonly<Record<string, string>>,\n): Promise<readonly string[]> {\n  const applied: string[] = [];\n  for (const intervention of recipe) {\n    const driver = intervention.driver;\n    if (driver?.pointer === 'outside') {\n      await target.mouse.move(-1, -1);\n      applied.push(intervention.id);\n    } else if (driver?.reducedMotion !== undefined) {\n      const preference = motionOf(declared?.[MOTION] ?? driver.reducedMotion);\n      await target.emulateMedia({ reducedMotion: preference });\n      // A declared `no-preference` is emulated and recorded among the features;\n      // the trick's id would claim a reduced motion the page never had.\n      if (preference === driver.reducedMotion) applied.push(intervention.id);\n    } else if (driver?.clock !== undefined) {\n      await target.addInitScript(freezeDate, driver.clock.at);\n      applied.push(intervention.id);\n    }\n  }\n  return applied;\n}\n\nfunction motionOf(value: string): MotionPreference {\n  if (value === 'reduce' || value === 'no-preference') return value;\n  throw new Error(\n    `\\`${MOTION}\\` is declared as ${JSON.stringify(value)}, which no browser reports; ` +\n      'declare \"reduce\" or \"no-preference\"',\n  );\n}\n\n/**\n * Take the pointer off the page again before a subject is read.\n *\n * For a host that shares the page: a test hovers a menu to open it and then\n * observes, so the pointer is wherever the test's last step left it. A host\n * that alone drives its page needs only {@link driveBeforeLoad}.\n *\n * Every reading pays the frame, hovered or not: measured in Chromium, a\n * Playwright hover restyles the element while `:hover` matches nothing from\n * script, so the page cannot say whether the move is needed. The pointer is\n * not put back afterwards, and the move fires `mouseleave`: a menu a script\n * opened on hover is closed for the test's next step.\n */\nexport async function driveBeforeRead(\n  recipe: readonly Intervention[],\n  target: Pick<DriverTarget, 'mouse'>,\n): Promise<readonly string[]> {\n  const applied: string[] = [];\n  for (const intervention of recipe) {\n    if (intervention.driver?.pointer === 'outside') {\n      await target.mouse.move(-1, -1);\n      applied.push(intervention.id);\n    }\n  }\n  return applied;\n}\n\n/**\n * The recipe as it holds on a page, given the driver tricks a host applied.\n *\n * A trick with no `driver` is kept. A trick with one is kept only when its id\n * is in `driven`: a host that could not drive it leaves it out of the ids and\n * the digest it records, rather than claiming a hold the page never had. The\n * clock is the one trick whose id the driver may change, because the instant is\n * the host's to choose: the recipe's clock is recorded as the one the host\n * fixed.\n */\nexport function forDriver(\n  recipe: readonly Intervention[],\n  driven: readonly string[],\n): readonly Intervention[] {\n  const fixed = driven.map((id) => (id === freezeClock.id ? freezeClock : clockById(id))).find(Boolean);\n  return recipe.flatMap((intervention) => {\n    if (intervention.driver === undefined || driven.includes(intervention.id)) return [intervention];\n    return intervention.driver.clock !== undefined && fixed !== undefined ? [fixed] : [];\n  });\n}\n"]}

package/dist/format/environment.d.ts

@@ -12,7 +12,7 @@ import type { ProfileId } from './profile.js';
  * treated as one. Leaving a field out is a correctness bug. When in doubt,
  * include it: over-invalidation costs CI minutes, under-invalidation costs trust.
  */
-export interface EnvironmentInputs {
+export interface EnvironmentInputs extends PageRegion {
     /** Which collector, and therefore which dimensions exist at all (ADR-0002). */
     readonly profile: ProfileId;
     /** Engine identity. `jsdom@26.1.0`, `chromium@131.0.6778.33`. */
@@ -60,6 +60,24 @@ export interface EnvironmentInputs {
      */
     readonly stabilization?: Digest;
 }
+/**
+ * The timezone a page's clock reads in and the language it formats for, as
+ * Playwright names them.
+ *
+ * A page that formats a date or a number without naming a timezone or a language
+ * of its own gets its browser's, so one build reads `12:30 AM` in one timezone
+ * and `4:30 PM` in another — different text, different widths, no edit anywhere.
+ * A collector that opened its page in a region it chose writes it to the
+ * environment key, the way the viewport carries its colour scheme. A field is
+ * absent where nobody chose it: a jsdom capture runs in its Node process, and an
+ * absent field says so rather than naming a timezone nobody set.
+ */
+export interface PageRegion {
+    /** An IANA timezone, such as `Europe/Berlin`. */
+    readonly timezoneId?: string;
+    /** A BCP 47 language tag, such as `de-DE`: a run's base locale (spec 0008). */
+    readonly locale?: string;
+}
 export interface Viewport {
     readonly width: number;
     readonly height: number;
@@ -111,7 +129,7 @@ export declare function environmentKey(inputs: EnvironmentInputs): EnvironmentKe
  * environments is a product feature, not a debugging aid.
  */
 export declare function diffEnvironments(before: EnvironmentInputs, after: EnvironmentInputs): readonly EnvironmentDelta[];
-export type EnvironmentField = 'profile' | 'engine' | 'ruleset' | 'allowlist' | 'viewport' | 'fonts' | 'conditions' | 'assets' | 'stabilization';
+export type EnvironmentField = 'profile' | 'engine' | 'ruleset' | 'allowlist' | 'viewport' | 'fonts' | 'conditions' | 'assets' | 'stabilization' | 'timezoneId' | 'locale';
 export interface EnvironmentDelta {
     readonly field: EnvironmentField;
     readonly from: string;

package/dist/format/environment.js

@@ -12,6 +12,11 @@ export function environmentKey(inputs) {
         // the recipe's first job is to stop an animation from moving `transform`,
         // which is a value the semantic representation carries.
         stabilization: inputs.stabilization,
+        // Text is laid out, so a timezone or a language reaches the box tree, and both
+        // keys carry them. `undefined` is omitted from the canonical form, so a
+        // capture that chose neither keeps the key it had before either existed.
+        timezoneId: inputs.timezoneId,
+        locale: inputs.locale,
     };
     // Layout depends on the viewport's size and colour scheme; rasterization also
     // depends on its scale factor. Splitting the viewport is what makes the two
@@ -48,6 +53,8 @@ export function diffEnvironments(before, after) {
     scalar('conditions', before.conditions, after.conditions);
     scalar('assets', before.assets, after.assets);
     scalar('stabilization', before.stabilization, after.stabilization);
+    scalar('timezoneId', before.timezoneId, after.timezoneId);
+    scalar('locale', before.locale, after.locale);
     return deltas;
 }
 //# sourceMappingURL=environment.js.map