@ploaness/governance 1.12.0 → 1.13.0

package/dist/browser-rules.d.ts

@@ -0,0 +1,169 @@
+import type { CandidateFinding } from './browser-exemptions.js';
+import { type LayoutSnapshot } from './layout-snapshot.js';
+/** The tolerance every geometric comparison allows, in CSS pixels. */
+export declare const GEOMETRY_TOLERANCE: number;
+/** The smallest rendered text size, in CSS pixels. */
+export declare const MINIMUM_TEXT_SIZE: number;
+/** How far an image may be enlarged beyond its natural resolution before it is judged upscaled. */
+export declare const UPSCALE_ALLOWANCE: number;
+/** The device pixel ratio every viewport is rendered at. */
+export declare const DEVICE_SCALE_FACTOR: number;
+/** The width of the ring around a focused element whose pixels the focus-visible rule compares. */
+export declare const FOCUS_RING_WIDTH: number;
+/** The element rules of the resting scan beyond geometry: T4 and M1 to M4. */
+export declare const RESTING_ELEMENT_RULES: readonly string[];
+/** The page rule of the resting scan: T6. */
+export declare const FONT_LOAD_RULE: string;
+/**
+ * Text rendered smaller than 12 CSS pixels (rule `small-text`).
+ * @param snapshot the measured page.
+ * @returns one candidate per element whose own text is too small.
+ */
+export declare const findSmallText: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+/**
+ * Visible images that did not load (rule `image-load`).
+ * @param snapshot the measured page.
+ * @returns one candidate per incomplete or empty image.
+ */
+export declare const findUnloadedImages: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+/**
+ * Images stretched out of their natural aspect ratio (rule `image-distorted`).
+ * @param snapshot the measured page.
+ * @returns one candidate per image whose `object-fit: fill` rendering changes its proportions.
+ */
+export declare const findDistortedImages: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+/**
+ * Images displayed larger than their source resolution allows (rule `image-upscaled`).
+ * @param snapshot the measured page.
+ * @returns one candidate per raster image enlarged by more than 10%.
+ */
+export declare const findUpscaledImages: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+/**
+ * Media whose box changes once its source loads, shifting what follows it (rule `media-space`).
+ * @param snapshot the measured page.
+ * @returns one candidate per in-flow element that does not reserve its rendered size.
+ */
+export declare const findUnreservedMedia: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+/**
+ * The declared font families the page's text asks for first.
+ * @param snapshot the measured page.
+ * @returns for each text element, the first family in its stack that has a `@font-face`.
+ */
+export declare const usedFontFamilies: (snapshot: LayoutSnapshot) => readonly string[];
+/**
+ * The `@font-face` families the page's text uses that did not load (rule `font-load`).
+ *
+ * A face the browser never needed stays `unloaded`, which is not a defect. A used family with no face
+ * loaded, or with a face that failed or is still loading after the page settled, is one. This proves the
+ * face loaded, not that every glyph avoided a fallback.
+ * @param snapshot the measured page.
+ * @returns one message per family.
+ */
+export declare const findUnloadedFonts: (snapshot: LayoutSnapshot) => readonly string[];
+/** One point of a focused element, and whether fixed or sticky content covers it. */
+export interface FocusSample {
+    readonly isCovered: boolean;
+    /** The label of what covers it, empty when nothing does. */
+    readonly coveredBy: string;
+}
+/**
+ * Whether a focused element is entirely hidden by fixed or sticky content (rule `focus-obscured`).
+ * @param samples points spread over the part of the element inside the viewport.
+ * @returns the label of the covering content, or undefined when any part of the element shows.
+ */
+export declare const obscuringContent: (samples: readonly FocusSample[]) => string | undefined;
+/**
+ * Whether two renderings of the same region differ, which is what a visible focus indicator does.
+ * @param unfocused the region's pixels with the element blurred.
+ * @param focused the same region with the element focused by keyboard.
+ * @returns true when at least one byte differs.
+ */
+export declare const hasVisibleFocus: (unfocused: Uint8Array, focused: Uint8Array) => boolean;
+/** The contrast a focus indicator's changed pixels need against what they replaced (WCAG 1.4.11). */
+export declare const FOCUS_CONTRAST_RATIO: number;
+/**
+ * The WCAG contrast ratio between two relative luminances.
+ * @param first one luminance.
+ * @param second the other.
+ * @returns the ratio, from 1 to 21.
+ */
+export declare const contrastRatio: (first: number, second: number) => number;
+/** A focused element's region rendered focused and unfocused, decoded to RGBA. */
+export interface FocusRenderings {
+    readonly unfocused: readonly number[];
+    readonly focused: readonly number[];
+    /** Device pixels per CSS pixel along one side. */
+    readonly scale: number;
+    /** The longer side of the element's visible box, in CSS pixels. */
+    readonly extent: number;
+}
+/**
+ * Whether a focus indicator contrasts with what it replaced (rule `focus-contrast`). The pixels whose
+ * focused colour contrasts at least 3:1 with their unfocused colour must cover as much as a one-pixel line
+ * along half the element's longer side, so an outline, a ring, an underline or a strong fill passes and a
+ * faint tint or glow does not.
+ * @param renderings the two renderings, their scale, and the element's longer side.
+ * @returns true when enough of the change contrasts.
+ */
+export declare const hasContrastingFocus: (renderings: FocusRenderings) => boolean;
+/** Where a keyboard-focused element sits, for the order focus moves in (rule `focus-order`). */
+export interface FocusPosition {
+    /** Its box in document coordinates, in CSS pixels. */
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+    /** The landmark it sits in; positions are compared only within one. */
+    readonly landmark: string;
+    /**
+     * Whether its position says nothing about order: it is in a dialog, in fixed or sticky content whose
+     * place moves with scrolling, or visually hidden.
+     */
+    readonly isUnplaced: boolean;
+    readonly isRightToLeft: boolean;
+}
+/**
+ * Whether focus moved backwards (rule `focus-order`): the next element sits entirely above the previous
+ * one in the same landmark. A next element in a column further along the line is not backwards, because
+ * that is where a reader goes after the foot of a column.
+ * @param previous where the previously focused element sits.
+ * @param next where the next focused element sits.
+ * @returns true when the move goes back up the page.
+ */
+export declare const isFocusBackwards: (previous: FocusPosition, next: FocusPosition) => boolean;
+/** What driving one opened disclosure with the keyboard showed. */
+export interface DisclosureProbe {
+    /** Whether the control declares a popup, which the keyboard pattern says `Escape` dismisses. */
+    readonly isPopup: boolean;
+    /** Whether `Escape` closed it. */
+    readonly closedOnEscape: boolean;
+    /** Whether focus was on the control after it closed. */
+    readonly focusReturned: boolean;
+    /** Whether it opened a modal dialog. */
+    readonly isModal: boolean;
+    /** Whether focus stayed inside that dialog while tabbing. */
+    readonly focusTrapped: boolean;
+}
+/**
+ * What is wrong with how a disclosure answers the keyboard (rule `disclosure-keyboard`).
+ *
+ * Only a popup or a modal dialog is required to close on `Escape`: the disclosure pattern for an
+ * accordion or a native `<details>` has no such key, and judging one by it would report the platform.
+ * @param probe what the keyboard showed.
+ * @returns one message per defect.
+ */
+export declare const disclosureDefects: (probe: DisclosureProbe) => readonly string[];
+/**
+ * Where two measurements of a settled page disagree (rule `page-not-stable`).
+ * @param first the first measurement.
+ * @param second the second, taken after it.
+ * @returns what moved, or undefined when the geometry held within the tolerance.
+ */
+export declare const instability: (first: LayoutSnapshot, second: LayoutSnapshot) => string | undefined;
+/**
+ * Every element candidate the resting scan's text and media rules find on one page.
+ * @param snapshot the measured page.
+ * @returns the candidates of T4 and M1 to M4.
+ */
+export declare const restingCandidates: (snapshot: LayoutSnapshot) => readonly CandidateFinding[];
+//# sourceMappingURL=browser-rules.d.ts.map

package/dist/browser-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-rules.d.ts","sourceRoot":"","sources":["../src/browser-rules.ts"],"names":[],"mappings":"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"}

package/dist/browser-rules.js

@@ -0,0 +1,345 @@
+import { hasArea, isInAriaHidden, isInClip, } from './layout-snapshot.js';
+/** The tolerance every geometric comparison allows, in CSS pixels. */
+export const GEOMETRY_TOLERANCE = 1;
+/** The smallest rendered text size, in CSS pixels. */
+export const MINIMUM_TEXT_SIZE = 12;
+/** How far an image may be enlarged beyond its natural resolution before it is judged upscaled. */
+export const UPSCALE_ALLOWANCE = 0.1;
+const PERCENT = 100;
+/** The device pixel ratio every viewport is rendered at. */
+export const DEVICE_SCALE_FACTOR = 1;
+/** The width of the ring around a focused element whose pixels the focus-visible rule compares. */
+export const FOCUS_RING_WIDTH = 4;
+/** The element rules of the resting scan beyond geometry: T4 and M1 to M4. */
+export const RESTING_ELEMENT_RULES = [
+    'small-text',
+    'image-load',
+    'image-distorted',
+    'image-upscaled',
+    'media-space',
+];
+/** The page rule of the resting scan: T6. */
+export const FONT_LOAD_RULE = 'font-load';
+const isRendered = (snapshot, node) => node.visibility === 'visible' &&
+    node.rects.some((rect) => hasArea(rect)) &&
+    !isInClip(snapshot, node) &&
+    !isInAriaHidden(snapshot, node);
+/**
+ * Text rendered smaller than 12 CSS pixels (rule `small-text`).
+ * @param snapshot the measured page.
+ * @returns one candidate per element whose own text is too small.
+ */
+export const findSmallText = (snapshot) => snapshot.nodes
+    .filter((node) => node.textRects.some((rect) => hasArea(rect)) &&
+    node.fontSize > 0 &&
+    node.fontSize < MINIMUM_TEXT_SIZE &&
+    isRendered(snapshot, node))
+    .map((node) => ({
+    rule: 'small-text',
+    subjects: [node],
+    message: `text rendered at ${String(node.fontSize)}px, below ${String(MINIMUM_TEXT_SIZE)}px: ${node.label}`,
+}));
+const renderedMedia = (snapshot) => snapshot.nodes.flatMap((node) => node.media !== undefined && isRendered(snapshot, node) ? [{ node, media: node.media }] : []);
+const isImage = (node) => node.tag === 'img';
+/**
+ * Visible images that did not load (rule `image-load`).
+ * @param snapshot the measured page.
+ * @returns one candidate per incomplete or empty image.
+ */
+export const findUnloadedImages = (snapshot) => renderedMedia(snapshot)
+    .filter(({ node, media }) => isImage(node) && (!media.isComplete || (!media.isVector && media.naturalWidth === 0)))
+    .map(({ node, media }) => ({
+    rule: 'image-load',
+    subjects: [node],
+    message: `image did not load (complete ${String(media.isComplete)}, ` +
+        `natural width ${String(media.naturalWidth)}): ${node.label}`,
+}));
+const hasRaster = (media) => !media.isVector && media.naturalWidth > 0 && media.naturalHeight > 0 && media.contentWidth > 0;
+/**
+ * Images stretched out of their natural aspect ratio (rule `image-distorted`).
+ * @param snapshot the measured page.
+ * @returns one candidate per image whose `object-fit: fill` rendering changes its proportions.
+ */
+export const findDistortedImages = (snapshot) => renderedMedia(snapshot).flatMap(({ node, media }) => {
+    if (!(isImage(node) && hasRaster(media)) || media.objectFit !== 'fill') {
+        return [];
+    }
+    const expectedHeight = (media.contentWidth * media.naturalHeight) / media.naturalWidth;
+    return Math.abs(expectedHeight - media.contentHeight) > GEOMETRY_TOLERANCE
+        ? [
+            {
+                rule: 'image-distorted',
+                subjects: [node],
+                message: `image rendered at ${String(media.contentWidth)}x${String(media.contentHeight)}px from a ` +
+                    `${String(media.naturalWidth)}x${String(media.naturalHeight)}px source, out of proportion: ${node.label}`,
+            },
+        ]
+        : [];
+});
+const displayedScale = (media) => {
+    const horizontal = media.contentWidth / media.naturalWidth;
+    const vertical = media.contentHeight / media.naturalHeight;
+    switch (media.objectFit) {
+        case 'cover': {
+            return Math.max(horizontal, vertical);
+        }
+        case 'contain': {
+            return Math.min(horizontal, vertical);
+        }
+        case 'none': {
+            return 1;
+        }
+        case 'scale-down': {
+            return Math.min(1, horizontal, vertical);
+        }
+        default: {
+            return Math.max(horizontal, vertical);
+        }
+    }
+};
+/**
+ * Images displayed larger than their source resolution allows (rule `image-upscaled`).
+ * @param snapshot the measured page.
+ * @returns one candidate per raster image enlarged by more than 10%.
+ */
+export const findUpscaledImages = (snapshot) => renderedMedia(snapshot).flatMap(({ node, media }) => {
+    if (!(isImage(node) && hasRaster(media))) {
+        return [];
+    }
+    const scale = displayedScale(media) * DEVICE_SCALE_FACTOR;
+    return scale > 1 + UPSCALE_ALLOWANCE
+        ? [
+            {
+                rule: 'image-upscaled',
+                subjects: [node],
+                message: `image source ${String(media.naturalWidth)}x${String(media.naturalHeight)}px displayed at ` +
+                    `${String(Math.round(scale * PERCENT))}% in a ` +
+                    `${String(media.contentWidth)}x${String(media.contentHeight)}px ` +
+                    `box; serve a larger source: ${node.label}`,
+            },
+        ]
+        : [];
+});
+const OUT_OF_FLOW = new Set(['absolute', 'fixed']);
+/**
+ * Media whose box changes once its source loads, shifting what follows it (rule `media-space`).
+ * @param snapshot the measured page.
+ * @returns one candidate per in-flow element that does not reserve its rendered size.
+ */
+export const findUnreservedMedia = (snapshot) => renderedMedia(snapshot).flatMap(({ node, media }) => {
+    if (OUT_OF_FLOW.has(node.position)) {
+        return [];
+    }
+    const rendered = node.rects[0];
+    if (rendered === undefined) {
+        return [];
+    }
+    const width = rendered.right - rendered.left;
+    const height = rendered.bottom - rendered.top;
+    return Math.abs(media.reservedWidth - width) > GEOMETRY_TOLERANCE ||
+        Math.abs(media.reservedHeight - height) > GEOMETRY_TOLERANCE
+        ? [
+            {
+                rule: 'media-space',
+                subjects: [node],
+                message: `${node.tag} reserves ${String(media.reservedWidth)}x${String(media.reservedHeight)}px before loading ` +
+                    `and takes ${String(width)}x${String(height)}px after; give it width and height attributes or an ` +
+                    `aspect-ratio: ${node.label}`,
+            },
+        ]
+        : [];
+});
+const GENERIC_FAMILIES = new Set([
+    'serif',
+    'sans-serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+    'math',
+    'emoji',
+    'fangsong',
+]);
+const familyName = (family) => family
+    .trim()
+    .replaceAll(/^["']|["']$/gu, '')
+    .toLowerCase();
+const familiesOf = (stack) => stack
+    .split(',')
+    .map((family) => familyName(family))
+    .filter((family) => family.length > 0 && !GENERIC_FAMILIES.has(family));
+/**
+ * The declared font families the page's text asks for first.
+ * @param snapshot the measured page.
+ * @returns for each text element, the first family in its stack that has a `@font-face`.
+ */
+export const usedFontFamilies = (snapshot) => {
+    const declared = new Set(snapshot.fontFaces.map((face) => familyName(face.family)));
+    return [
+        ...new Set(snapshot.nodes
+            .filter((node) => node.textRects.length > 0)
+            .flatMap((node) => {
+            const first = familiesOf(node.fontFamily).find((family) => declared.has(family));
+            return first === undefined ? [] : [first];
+        })),
+    ];
+};
+/**
+ * The `@font-face` families the page's text uses that did not load (rule `font-load`).
+ *
+ * A face the browser never needed stays `unloaded`, which is not a defect. A used family with no face
+ * loaded, or with a face that failed or is still loading after the page settled, is one. This proves the
+ * face loaded, not that every glyph avoided a fallback.
+ * @param snapshot the measured page.
+ * @returns one message per family.
+ */
+export const findUnloadedFonts = (snapshot) => usedFontFamilies(snapshot).flatMap((family) => {
+    const faces = snapshot.fontFaces.filter((face) => familyName(face.family) === family);
+    const failed = faces.filter((face) => face.status === 'error' || face.status === 'loading');
+    if (failed.length > 0) {
+        return failed.map((face) => `@font-face "${face.family}" ${face.weight} ${face.style} is ${face.status} after the page settled`);
+    }
+    return faces.some((face) => face.status === 'loaded')
+        ? []
+        : [`@font-face "${family}" is used by the page's text and none of its faces loaded`];
+});
+/**
+ * Whether a focused element is entirely hidden by fixed or sticky content (rule `focus-obscured`).
+ * @param samples points spread over the part of the element inside the viewport.
+ * @returns the label of the covering content, or undefined when any part of the element shows.
+ */
+export const obscuringContent = (samples) => samples.length > 0 && samples.every((sample) => sample.isCovered)
+    ? [...new Set(samples.map((sample) => sample.coveredBy))].join(', ')
+    : undefined;
+/**
+ * Whether two renderings of the same region differ, which is what a visible focus indicator does.
+ * @param unfocused the region's pixels with the element blurred.
+ * @param focused the same region with the element focused by keyboard.
+ * @returns true when at least one byte differs.
+ */
+export const hasVisibleFocus = (unfocused, focused) => unfocused.length !== focused.length ||
+    unfocused.some((byte, index) => byte !== focused[index]);
+/** The contrast a focus indicator's changed pixels need against what they replaced (WCAG 1.4.11). */
+export const FOCUS_CONTRAST_RATIO = 3;
+const RGBA_BYTES = 4;
+const CHANNEL_MAX = 255;
+const LINEAR_KNEE = 0.04045;
+const LINEAR_SLOPE = 12.92;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_SCALE = 1.055;
+const GAMMA = 2.4;
+const RED_WEIGHT = 0.2126;
+const GREEN_WEIGHT = 0.7152;
+const BLUE_WEIGHT = 0.0722;
+const FLARE = 0.05;
+const BLUE_OFFSET = 2;
+// The share of the element's longer side a contrasting one-pixel line must cover.
+const LINE_SHARE = 0.5;
+const linearChannel = (value) => {
+    const fraction = value / CHANNEL_MAX;
+    return fraction <= LINEAR_KNEE ? fraction / LINEAR_SLOPE : ((fraction + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA;
+};
+const luminanceAt = (pixels, offset) => RED_WEIGHT * linearChannel(pixels[offset] ?? 0) +
+    GREEN_WEIGHT * linearChannel(pixels[offset + 1] ?? 0) +
+    BLUE_WEIGHT * linearChannel(pixels[offset + BLUE_OFFSET] ?? 0);
+/**
+ * The WCAG contrast ratio between two relative luminances.
+ * @param first one luminance.
+ * @param second the other.
+ * @returns the ratio, from 1 to 21.
+ */
+export const contrastRatio = (first, second) => (Math.max(first, second) + FLARE) / (Math.min(first, second) + FLARE);
+/**
+ * Whether a focus indicator contrasts with what it replaced (rule `focus-contrast`). The pixels whose
+ * focused colour contrasts at least 3:1 with their unfocused colour must cover as much as a one-pixel line
+ * along half the element's longer side, so an outline, a ring, an underline or a strong fill passes and a
+ * faint tint or glow does not.
+ * @param renderings the two renderings, their scale, and the element's longer side.
+ * @returns true when enough of the change contrasts.
+ */
+export const hasContrastingFocus = (renderings) => {
+    const { unfocused, focused, scale, extent } = renderings;
+    const pixels = Math.floor(Math.min(unfocused.length, focused.length) / RGBA_BYTES);
+    const contrasting = Array.from({ length: pixels }, (_unused, pixel) => pixel).filter((pixel) => contrastRatio(luminanceAt(unfocused, pixel * RGBA_BYTES), luminanceAt(focused, pixel * RGBA_BYTES)) >=
+        FOCUS_CONTRAST_RATIO).length;
+    return contrasting / (scale * scale) >= extent * LINE_SHARE;
+};
+/**
+ * Whether focus moved backwards (rule `focus-order`): the next element sits entirely above the previous
+ * one in the same landmark. A next element in a column further along the line is not backwards, because
+ * that is where a reader goes after the foot of a column.
+ * @param previous where the previously focused element sits.
+ * @param next where the next focused element sits.
+ * @returns true when the move goes back up the page.
+ */
+export const isFocusBackwards = (previous, next) => {
+    if (previous.isUnplaced || next.isUnplaced || previous.landmark !== next.landmark) {
+        return false;
+    }
+    const isFurtherAlong = previous.isRightToLeft ? next.right <= previous.left : next.left >= previous.right;
+    return next.bottom <= previous.top && !isFurtherAlong;
+};
+const escapeDefects = (probe) => {
+    if (!(probe.isPopup || probe.isModal)) {
+        return [];
+    }
+    if (!probe.closedOnEscape) {
+        return ['Escape does not close it'];
+    }
+    return probe.focusReturned ? [] : ['focus does not return to its control after Escape'];
+};
+/**
+ * What is wrong with how a disclosure answers the keyboard (rule `disclosure-keyboard`).
+ *
+ * Only a popup or a modal dialog is required to close on `Escape`: the disclosure pattern for an
+ * accordion or a native `<details>` has no such key, and judging one by it would report the platform.
+ * @param probe what the keyboard showed.
+ * @returns one message per defect.
+ */
+export const disclosureDefects = (probe) => [
+    ...escapeDefects(probe),
+    ...(probe.isModal && !probe.focusTrapped ? ['focus leaves the open modal dialog while tabbing'] : []),
+];
+const isSameRect = (left, right) => Math.abs(left.left - right.left) <= GEOMETRY_TOLERANCE &&
+    Math.abs(left.top - right.top) <= GEOMETRY_TOLERANCE &&
+    Math.abs(left.right - right.right) <= GEOMETRY_TOLERANCE &&
+    Math.abs(left.bottom - right.bottom) <= GEOMETRY_TOLERANCE;
+const isSameNode = (left, right) => left.label === right.label &&
+    left.rects.length === right.rects.length &&
+    left.rects.every((rect, index) => {
+        const other = right.rects[index];
+        return other !== undefined && isSameRect(rect, other);
+    });
+/**
+ * Where two measurements of a settled page disagree (rule `page-not-stable`).
+ * @param first the first measurement.
+ * @param second the second, taken after it.
+ * @returns what moved, or undefined when the geometry held within the tolerance.
+ */
+export const instability = (first, second) => {
+    if (first.nodes.length !== second.nodes.length) {
+        return `the element count changed from ${String(first.nodes.length)} to ${String(second.nodes.length)}`;
+    }
+    const moved = first.nodes.find((node, index) => {
+        const other = second.nodes[index];
+        return other === undefined || !isSameNode(node, other);
+    });
+    return moved === undefined ? undefined : `${moved.label} moved between two measurements`;
+};
+/**
+ * Every element candidate the resting scan's text and media rules find on one page.
+ * @param snapshot the measured page.
+ * @returns the candidates of T4 and M1 to M4.
+ */
+export const restingCandidates = (snapshot) => [
+    ...findSmallText(snapshot),
+    ...findUnloadedImages(snapshot),
+    ...findDistortedImages(snapshot),
+    ...findUpscaledImages(snapshot),
+    ...findUnreservedMedia(snapshot),
+];
+//# sourceMappingURL=browser-rules.js.map

package/dist/browser-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-rules.js","sourceRoot":"","sources":["../src/browser-rules.ts"],"names":[],"mappings":"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"}

package/dist/browser-run.d.ts

@@ -0,0 +1,110 @@
+/** The variable naming the instant the application's clock starts at, or absent for the real clock. */
+export declare const CLOCK_ENVIRONMENT_VARIABLE: string;
+/**
+ * The instant every verification run starts its clocks at.
+ *
+ * Far in the future on purpose. The browser's cookie store keeps real time, so a shifted server that
+ * believed it was earlier than now would set absolute cookie expiries the browser already considers
+ * past, and every sign-in would fail. Noon, so that a run lasting hours still sees one date.
+ */
+export declare const DEFAULT_CLOCK_INSTANT: string;
+/** The clock setting that leaves every clock real. */
+export declare const REAL_CLOCK: string;
+/**
+ * The clock a project declared: an ISO instant, `"real"`, or the default instant for anything else.
+ * @param declared the raw `ploaness.clock` value.
+ * @returns the ISO instant to start at, or `"real"`.
+ */
+export declare const clockOf: (declared: unknown) => string;
+/**
+ * The time a shifted clock reads: the instant it started at, advanced by the real time since.
+ * @param instantMs the instant the clock started at.
+ * @param startedMs the real time it started.
+ * @param realMs the real time now.
+ * @returns the shifted time now.
+ */
+export declare const shiftedTime: (instantMs: number, startedMs: number, realMs: number) => number;
+/** The variable naming the pinned browser server the suite connects to. */
+export declare const BROWSER_ENDPOINT_ENVIRONMENT_VARIABLE: string;
+/**
+ * The pinned Playwright image whose browsers a verification run measures in.
+ * @param version the `@playwright/test` version ploaness pins.
+ * @returns the image reference.
+ */
+export declare const playwrightImageOf: (version: string) => string;
+/** The engines a verification run measures in. Outside verification only the first runs. */
+export declare const BROWSER_ENGINES: readonly string[];
+/** The passes the sweep runs, in order. */
+export type SweepPass = 'discovery' | 'resting' | 'interaction' | 'disclosures' | 'text-stress' | 'width-sweep' | 'dark-scheme' | 'engine';
+/** The rule a pass that ran out of time reports. */
+export declare const PASS_BUDGET_RULE: string;
+/**
+ * The time a pass may take, derived from the work it discovered.
+ * @param pass the pass.
+ * @param units how many units of work it has.
+ * @returns its budget in milliseconds.
+ */
+export declare const passBudgetMs: (pass: SweepPass, units: number) => number;
+/** The workers a browser run spreads the sweep's tests over. */
+export declare const SWEEP_WORKERS: number;
+/** How many tests each sweep pass is split into, so its parts run on parallel workers. */
+export declare const SWEEP_SHARDS: number;
+/** One part of a sweep pass: its zero-based index among `count` parts. */
+export interface Shard {
+    readonly index: number;
+    readonly count: number;
+}
+/** An item a shard visits, with its index in the whole pass. */
+export interface ShardItem<Item> {
+    readonly item: Item;
+    readonly index: number;
+}
+/**
+ * The time one part of a pass may take. The parts take the pass's items from one queue, so each does an
+ * equal share of the work whatever items it happens to take.
+ * @param pass the pass.
+ * @param units how many units of work the whole pass has.
+ * @param shard the part.
+ * @returns its budget in milliseconds.
+ */
+export declare const partBudgetMs: (pass: SweepPass, units: number, shard: Shard) => number;
+/** What starting the pinned browser server needs to know. */
+export interface PinnedBrowserServer {
+    readonly image: string;
+    readonly name: string;
+    readonly port: number;
+    /** The host's resolved `playwright-core` directory, which the container runs. */
+    readonly playwrightCore: string;
+    /**
+     * Whether the container shares the host's network. It then reaches the application's loopback
+     * origins directly; otherwise every request a page makes travels through the client's tunnel, which
+     * costs several times the load itself.
+     */
+    readonly isHostNetwork: boolean;
+    /**
+     * A random path the server answers on. The port is free when it is chosen and taken by the container
+     * a moment later, so another local process could take it first and pose as the browser server; it
+     * cannot complete the handshake on a path it was never told.
+     */
+    readonly secret: string;
+}
+/** The variable telling the suite its pinned browsers reach the application only through the tunnel. */
+export declare const BROWSER_TUNNEL_ENVIRONMENT_VARIABLE: string;
+/**
+ * The `docker` arguments that start the pinned browser server.
+ *
+ * The container runs the host's own `playwright-core` against the image's browsers, so nothing is
+ * fetched at test time and the protocol on both ends is one version. It listens on loopback only: on the
+ * host's own when the container shares the host network, or on a port published to it.
+ * @param server the server to start.
+ * @returns the arguments after `docker`.
+ */
+export declare const pinnedBrowserServerArguments: (server: PinnedBrowserServer) => readonly string[];
+/**
+ * The endpoint the suite connects to.
+ * @param port the published port.
+ * @param secret the path the server answers on.
+ * @returns the WebSocket URL.
+ */
+export declare const pinnedBrowserEndpoint: (port: number, secret: string) => string;
+//# sourceMappingURL=browser-run.d.ts.map

package/dist/browser-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-run.d.ts","sourceRoot":"","sources":["../src/browser-run.ts"],"names":[],"mappings":"AAGA,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,EAAE,MAAyB,CAAA;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAmC,CAAA;AAEvE,sDAAsD;AACtD,eAAO,MAAM,UAAU,EAAE,MAAe,CAAA;AAIxC;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAI,UAAU,OAAO,KAAG,MAO3C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,WAAW,MAAM,EAAE,WAAW,MAAM,EAAE,QAAQ,MAAM,KAAG,MACjD,CAAA;AAElC,2EAA2E;AAC3E,eAAO,MAAM,qCAAqC,EAAE,MAAoC,CAAA;AAExF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,MAA0D,CAAA;AAE9G,4FAA4F;AAC5F,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAsC,CAAA;AAEnF,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,SAAS,GACT,aAAa,GACb,aAAa,GACb,aAAa,GACb,aAAa,GACb,aAAa,GACb,QAAQ,CAAA;AAmBZ,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,EAAE,MAAsB,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,EAAE,OAAO,MAAM,KAAG,MACD,CAAA;AAK7D,gEAAgE;AAChE,eAAO,MAAM,aAAa,EAAE,MAAU,CAAA;AAEtC,0FAA0F;AAC1F,eAAO,MAAM,YAAY,EAAE,MAAU,CAAA;AAErC,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,SAAS,CAAC,IAAI;IAC7B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,EAAE,OAAO,MAAM,EAAE,OAAO,KAAK,KAAG,MACxB,CAAA;AAKpD,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,wGAAwG;AACxG,eAAO,MAAM,mCAAmC,EAAE,MAAkC,CAAA;AAEpF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,mBAAmB,KAAG,SAAS,MAAM,EAiBzF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,MACzB,CAAA"}