tslaws 0.0.0-stage → 0.3.2

package/dist/api.d.ts

@@ -0,0 +1,59 @@
+import * as fc from 'fast-check';
+export { fc };
+/**
+ * An integer the prover treats exactly (within the safe integers) instead of as an IEEE double, so laws over it can be
+ * proved. At runtime it is an ordinary number.
+ */
+export type int = number & {
+    readonly __tslawsInt: true;
+};
+/** Thrown by `assume`; the runner skips the input. */
+export declare class LawDiscard extends Error {
+    constructor();
+}
+/** Skips the current input unless `condition` holds. */
+export declare function assume(condition: boolean): asserts condition;
+/**
+ * Loop invariant: put it first in a loop body. At runtime it throws when false, so property tests check it on every
+ * iteration; the prover assumes it at the top of an arbitrary iteration and proves it again at the end, which makes the
+ * loop's result a proof for every number of iterations instead of a bounded one.
+ */
+export declare function invariant(condition: boolean): void;
+/**
+ * True when `predicate(x, i)` holds for every element of `xs`. In a law the prover lowers it over the array's slots, so
+ * a claim that relies on it is `bounded` by `--bound` like any array claim. The predicate must be an arrow function
+ * the prover can lower; otherwise the law stays `tested`.
+ */
+export declare function forall<T>(xs: readonly T[], predicate: (x: T, i: number) => boolean): boolean;
+/** True when `predicate(x, i)` holds for some element of `xs`; the prover lowers it as `forall` does. */
+export declare function exists<T>(xs: readonly T[], predicate: (x: T, i: number) => boolean): boolean;
+/** Where the latest `runModel` / `runModelAsync` call diverged (`step` is the op index, -1 before the first op), or undefined if it agreed. */
+export declare function modelFailure(): {
+    step: number;
+    op: unknown;
+} | undefined;
+/**
+ * Stateful law helper: applies `ops` to `real` and to a simple reference `model` and returns false at the first step
+ * after which `agree` fails (`agree` is also checked before the first op). `apply` performs the op on `real` and returns
+ * the next model state. Use it in a law over `ops: Op[]` so failing sequences shrink to the shortest one. On a
+ * disagreement `modelFailure()` names the step and op.
+ */
+export declare function runModel<Op, Real, Model>(spec: {
+    ops: readonly Op[];
+    real: Real;
+    model: Model;
+    apply: (real: Real, model: Model, op: Op, step: number) => Model;
+    agree: (real: Real, model: Model) => boolean;
+}): boolean;
+/** `runModel` for `apply` and `agree` that return promises (a browser law can click and `await settle()`). */
+export declare function runModelAsync<Op, Real, Model>(spec: {
+    ops: readonly Op[];
+    real: Real;
+    model: Model;
+    apply: (real: Real, model: Model, op: Op, step: number) => Model | Promise<Model>;
+    agree: (real: Real, model: Model) => boolean | Promise<boolean>;
+}): Promise<boolean>;
+type Registry = Map<string, fc.Arbitrary<unknown>>;
+export declare function arbitraryRegistry(): Registry;
+/** Registers the generator used for every parameter whose type is named `typeName`. */
+export declare function arbitrary<T>(typeName: string, generator: fc.Arbitrary<T>): void;

package/dist/api.js

@@ -0,0 +1,103 @@
+// What a laws file imports: `assume` to discard inputs a law does not cover, and `arbitrary` to register
+// a generator for a named type the runner cannot derive.
+import * as fc from 'fast-check';
+export { fc };
+/** Thrown by `assume`; the runner skips the input. */
+export class LawDiscard extends Error {
+    constructor() {
+        super('law input discarded');
+        this.name = 'LawDiscard';
+    }
+}
+/** Skips the current input unless `condition` holds. */
+export function assume(condition) {
+    if (!condition)
+        throw new LawDiscard();
+}
+/**
+ * Loop invariant: put it first in a loop body. At runtime it throws when false, so property tests check it on every
+ * iteration; the prover assumes it at the top of an arbitrary iteration and proves it again at the end, which makes the
+ * loop's result a proof for every number of iterations instead of a bounded one.
+ */
+export function invariant(condition) {
+    if (!condition)
+        throw new Error('loop invariant violated');
+}
+/**
+ * True when `predicate(x, i)` holds for every element of `xs`. In a law the prover lowers it over the array's slots, so
+ * a claim that relies on it is `bounded` by `--bound` like any array claim. The predicate must be an arrow function
+ * the prover can lower; otherwise the law stays `tested`.
+ */
+export function forall(xs, predicate) {
+    for (let i = 0; i < xs.length; i += 1)
+        if (!predicate(xs[i], i))
+            return false;
+    return true;
+}
+/** True when `predicate(x, i)` holds for some element of `xs`; the prover lowers it as `forall` does. */
+export function exists(xs, predicate) {
+    for (let i = 0; i < xs.length; i += 1)
+        if (predicate(xs[i], i))
+            return true;
+    return false;
+}
+let lastModelFailure;
+/** Where the latest `runModel` / `runModelAsync` call diverged (`step` is the op index, -1 before the first op), or undefined if it agreed. */
+export function modelFailure() {
+    return lastModelFailure;
+}
+/**
+ * Stateful law helper: applies `ops` to `real` and to a simple reference `model` and returns false at the first step
+ * after which `agree` fails (`agree` is also checked before the first op). `apply` performs the op on `real` and returns
+ * the next model state. Use it in a law over `ops: Op[]` so failing sequences shrink to the shortest one. On a
+ * disagreement `modelFailure()` names the step and op.
+ */
+export function runModel(spec) {
+    lastModelFailure = undefined;
+    let model = spec.model;
+    if (!spec.agree(spec.real, model)) {
+        lastModelFailure = { step: -1, op: undefined };
+        return false;
+    }
+    for (let step = 0; step < spec.ops.length; step += 1) {
+        const op = spec.ops[step];
+        model = spec.apply(spec.real, model, op, step);
+        if (!spec.agree(spec.real, model)) {
+            lastModelFailure = { step, op };
+            return false;
+        }
+    }
+    return true;
+}
+/** `runModel` for `apply` and `agree` that return promises (a browser law can click and `await settle()`). */
+export async function runModelAsync(spec) {
+    lastModelFailure = undefined;
+    let model = spec.model;
+    if (!(await spec.agree(spec.real, model))) {
+        lastModelFailure = { step: -1, op: undefined };
+        return false;
+    }
+    for (let step = 0; step < spec.ops.length; step += 1) {
+        const op = spec.ops[step];
+        model = await spec.apply(spec.real, model, op, step);
+        if (!(await spec.agree(spec.real, model))) {
+            lastModelFailure = { step, op };
+            return false;
+        }
+    }
+    return true;
+}
+const registryKey = Symbol.for('tslaws.arbitraries');
+export function arbitraryRegistry() {
+    const holder = globalThis;
+    let registry = holder[registryKey];
+    if (registry === undefined) {
+        registry = new Map();
+        holder[registryKey] = registry;
+    }
+    return registry;
+}
+/** Registers the generator used for every parameter whose type is named `typeName`. */
+export function arbitrary(typeName, generator) {
+    arbitraryRegistry().set(typeName, generator);
+}

package/dist/browser.d.ts

@@ -0,0 +1,24 @@
+import { type Browser } from 'playwright-core';
+import type * as fc from 'fast-check';
+import { type PropertyOutcome } from './property.ts';
+import type { CheckOptions } from './types.ts';
+/** `a.browser.laws.ts` runs in a browser. */
+export declare function isBrowserLawFile(file: string): boolean;
+export type BrowserEngine = 'chromium' | 'firefox' | 'webkit';
+/** The engine to use: the requested one, else `TSLAWS_BROWSER_ENGINE`, else chromium. Throws on an unknown name. */
+export declare function resolveEngine(requested?: string, env?: NodeJS.ProcessEnv): BrowserEngine;
+/**
+ * The executable to launch for an engine. Chromium falls back to an installed Chrome or Edge; Firefox and WebKit use
+ * TSLAWS_BROWSER or Playwright's own download. Throws, naming the install command, when there is none.
+ */
+export declare function engineExecutable(engine: BrowserEngine, env?: NodeJS.ProcessEnv): string;
+export declare function launch(engine: BrowserEngine): Promise<Browser>;
+export declare function closeBrowser(): Promise<void>;
+export interface BrowserLaw {
+    file: string;
+    name: string;
+    jsFile: string;
+    generators: fc.Arbitrary<unknown>[];
+}
+/** Property-tests one law in a page; `'timeout'` when it does not finish within `options.propertyTimeoutMs`. */
+export declare function runBrowserLaw(law: BrowserLaw, options: CheckOptions): Promise<PropertyOutcome | 'timeout'>;

package/dist/browser.js

@@ -0,0 +1,252 @@
+// Runs laws in a real browser. Node generates the inputs (from the declared types, with shrinking, like any law), and
+// each input is sent to a page where the compiled law and the code it checks run against a live DOM.
+import { existsSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { build as bundleWith } from 'esbuild';
+import { chromium, firefox, webkit } from 'playwright-core';
+import { toWire } from "./generators.js";
+import { runProperty, summarise } from "./property.js";
+/** `a.browser.laws.ts` runs in a browser. */
+export function isBrowserLawFile(file) {
+    return /\.browser\.laws\.[cm]?ts$/.test(file);
+}
+function findBrowser() {
+    const fromEnv = process.env.TSLAWS_BROWSER;
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    const candidates = [];
+    if (process.platform === 'win32') {
+        for (const base of [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA]) {
+            if (base === undefined)
+                continue;
+            candidates.push(join(base, 'Google/Chrome/Application/chrome.exe'), join(base, 'Microsoft/Edge/Application/msedge.exe'));
+        }
+    }
+    else if (process.platform === 'darwin') {
+        candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/Applications/Chromium.app/Contents/MacOS/Chromium');
+    }
+    else {
+        for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+            for (const name of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge'])
+                candidates.push(join(dir, name));
+        }
+    }
+    try {
+        candidates.push(chromium.executablePath());
+    }
+    catch {
+        // Playwright has no browser of its own installed.
+    }
+    return candidates.find((c) => existsSync(c));
+}
+const engines = ['chromium', 'firefox', 'webkit'];
+/** The engine to use: the requested one, else `TSLAWS_BROWSER_ENGINE`, else chromium. Throws on an unknown name. */
+export function resolveEngine(requested, env = process.env) {
+    const name = (requested ?? env.TSLAWS_BROWSER_ENGINE ?? '').trim().toLowerCase();
+    if (name === '')
+        return 'chromium';
+    if (engines.includes(name))
+        return name;
+    throw new Error(`unknown browser engine '${name}': use chromium, firefox or webkit`);
+}
+/**
+ * The executable to launch for an engine. Chromium falls back to an installed Chrome or Edge; Firefox and WebKit use
+ * TSLAWS_BROWSER or Playwright's own download. Throws, naming the install command, when there is none.
+ */
+export function engineExecutable(engine, env = process.env) {
+    if (engine === 'chromium') {
+        const found = findBrowser();
+        if (found === undefined)
+            throw new Error('no browser found: install Chrome, Edge or Chromium, or set TSLAWS_BROWSER to its executable');
+        return found;
+    }
+    const fromEnv = env.TSLAWS_BROWSER;
+    let path = fromEnv !== undefined && fromEnv !== '' ? fromEnv : undefined;
+    if (path === undefined) {
+        try {
+            path = (engine === 'firefox' ? firefox : webkit).executablePath();
+        }
+        catch {
+            // Playwright has no such browser installed.
+        }
+    }
+    if (path === undefined || !existsSync(path))
+        throw new Error(`no ${engine} installed: run \`npx playwright install ${engine}\` or set TSLAWS_BROWSER to its executable`);
+    return path;
+}
+const browsers = new Map();
+export function launch(engine) {
+    let open = browsers.get(engine);
+    if (open === undefined) {
+        const type = { chromium, firefox, webkit }[engine];
+        open = (async () => type.launch({ executablePath: engineExecutable(engine), headless: true }))();
+        open.catch(() => browsers.delete(engine));
+        browsers.set(engine, open);
+    }
+    return open;
+}
+export async function closeBrowser() {
+    const open = [...browsers.values()];
+    browsers.clear();
+    for (const one of open) {
+        try {
+            await (await one).close();
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+// Runs inside the page: the law, a clean DOM before and after, and a result that survives structured cloning.
+const harness = `
+window.__runLaw = async (name, args, keep, pause) => {
+  const clean = () => {
+    for (const undo of (window.__tslawsCleanup || []).splice(0)) { try { undo(); } catch (e) {} }
+    document.body.innerHTML = '';
+  };
+  // Functions cannot cross into the page: generated ones arrive as { $tslawsFn: samples } and are rebuilt here.
+  const revive = (v) => {
+    if (Array.isArray(v)) return v.map(revive);
+    if (v && typeof v === 'object') {
+      if (Array.isArray(v.$tslawsFn)) {
+        const samples = v.$tslawsFn;
+        return (...a) => {
+          let key = '';
+          try { key = JSON.stringify(a) || ''; } catch (e) {}
+          let h = 5381;
+          for (let i = 0; i < key.length; i++) h = (Math.imul(h, 33) + key.charCodeAt(i)) | 0;
+          return samples[(h >>> 0) % samples.length];
+        };
+      }
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, revive(x)]));
+    }
+    return v;
+  };
+  clean();
+  try {
+    const result = await window.__lawModule[name](...revive(args));
+    return { ok: result !== false };
+  } catch (error) {
+    return { error: { name: error && error.name, message: error && error.message ? error.message : String(error) } };
+  } finally {
+    if (pause > 0) {
+      window.__shown = true;
+      await new Promise((done) => setTimeout(done, pause));
+      window.__shown = false;
+    }
+    if (!keep) clean();
+  }
+};`;
+// Bare imports resolve from the project's own node_modules first (a JSX runtime, a UI library, axe-core), then the
+// usual way. axe-core is an optional peer dependency: without a copy the import stays for the page to fail on (a11y()
+// turns that into a clear message), so projects without it still bundle.
+function projectModulesPlugin(cwd) {
+    return {
+        name: 'tslaws-project-modules',
+        setup(build) {
+            build.onResolve({ filter: /^[^./]/ }, async (args) => {
+                if (args.pluginData === 'tslaws' || args.kind === 'entry-point' || /^[a-zA-Z]:/.test(args.path))
+                    return undefined;
+                const found = await build.resolve(args.path, { kind: args.kind, resolveDir: cwd, pluginData: 'tslaws' });
+                if (found.errors.length === 0)
+                    return { path: found.path, external: found.external, sideEffects: found.sideEffects };
+                return args.path === 'axe-core' ? { path: 'axe-core', external: true } : undefined;
+            });
+        },
+    };
+}
+async function bundleOf(jsFile, cwd) {
+    const result = await bundleWith({
+        plugins: [projectModulesPlugin(cwd)],
+        entryPoints: [jsFile],
+        bundle: true,
+        write: false,
+        format: 'iife',
+        globalName: '__lawModule',
+        platform: 'browser',
+        target: 'es2022',
+        absWorkingDir: cwd,
+        logLevel: 'silent',
+        define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
+    });
+    return result.outputFiles[0].text;
+}
+/** Runs the counterexample once more, leaves the DOM as it is, and photographs the page. Best effort. */
+async function capture(page, law, args, options) {
+    try {
+        await page.evaluate(([name, input]) => window.__runLaw(name, input, true), [law.name, toWire(args)]);
+        const relative = `.tslaws/screenshots/${law.name.replace(/[^\w-]/g, '_')}.png`;
+        mkdirSync(join(options.cwd, '.tslaws/screenshots'), { recursive: true });
+        await page.screenshot({ path: join(options.cwd, relative) });
+        return relative;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Property-tests one law in a page; `'timeout'` when it does not finish within `options.propertyTimeoutMs`. */
+export async function runBrowserLaw(law, options) {
+    const code = await bundleOf(law.jsFile, options.cwd);
+    const page = await (await launch(resolveEngine(options.browser))).newPage();
+    // A watcher needs only the first few runs to linger; the rest should not eat the time limit.
+    let calls = 0;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        void page.close();
+    }, options.propertyTimeoutMs ?? 30000);
+    const pageErrors = [];
+    page.on('pageerror', (error) => pageErrors.push(error.message));
+    // While someone watches, photograph the page a few times a second.
+    let framing = false;
+    const frames = options.onEvent
+        ? setInterval(() => {
+            if (framing || page.isClosed())
+                return;
+            framing = true;
+            // Only while the law has left the page as it wants it seen, not between runs when it is empty.
+            page
+                .evaluate(() => window.__shown === true)
+                .then((shown) => (shown ? page.screenshot({ type: 'jpeg', quality: 55, timeout: 2000 }) : undefined))
+                .then((jpeg) => jpeg === undefined ? undefined : options.onEvent?.({ type: 'frame', file: law.file, name: law.name, jpeg }))
+                .catch(() => undefined)
+                .finally(() => (framing = false));
+        }, 120)
+        : undefined;
+    try {
+        await page.setContent('<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>');
+        await page.addScriptTag({ content: code });
+        await page.addScriptTag({ content: harness });
+        const call = async (...args) => {
+            const outcome = (await page.evaluate(([name, input, pause]) => window.__runLaw(name, input, false, pause), [law.name, toWire(args), calls++ < 12 ? (options.browserPauseMs ?? 0) : 0]));
+            if (outcome.error !== undefined) {
+                const error = new Error(outcome.error.message);
+                error.name = outcome.error.name ?? 'Error';
+                throw error;
+            }
+            return outcome.ok;
+        };
+        const details = await runProperty(call, law.generators, options);
+        // Closing the page fails the call in flight, which the property reports as a failure of the law.
+        if (timedOut)
+            return 'timeout';
+        const outcome = summarise(details, options);
+        if (details.failed && details.counterexample !== null && !page.isClosed())
+            outcome.screenshot = await capture(page, law, details.counterexample, options);
+        return outcome;
+    }
+    catch (error) {
+        if (timedOut)
+            return 'timeout';
+        const extra = pageErrors.length > 0 ? ` (page error: ${pageErrors[0]})` : '';
+        throw new Error(`${error.message}${extra}`);
+    }
+    finally {
+        clearTimeout(timer);
+        if (frames !== undefined)
+            clearInterval(frames);
+        if (!page.isClosed())
+            await page.close();
+    }
+}

package/dist/browserApi.d.ts

@@ -0,0 +1,62 @@
+type Cleanup = () => void;
+/**
+ * A fresh container in the page, removed after the law. Pass markup, a node, or a function that renders into the
+ * container (a framework's `render` call) and may return what undoes it (an `unmount`).
+ */
+export declare function mount(content?: string | Node | ((container: HTMLElement) => void | Cleanup)): HTMLElement;
+/** Waits until pending microtasks, timers and animation frames have run, so the DOM has caught up. */
+export declare function settle(frames?: number): Promise<void>;
+/** Dispatches a bubbling event. */
+export declare function fire(target: EventTarget, type: string, init?: EventInit): boolean;
+/** A real click: pointer events, then `click`. */
+export declare function click(target: Element): void;
+/** Sets a field's value the way typing does, so frameworks that track `input` events notice. */
+export declare function type(field: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, text: string): void;
+export interface A11yViolation {
+    id: string;
+    impact: string | null;
+    help: string;
+    /** Outer HTML of each offending element, trimmed to 200 characters. */
+    nodes: string[];
+}
+export interface A11yOptions {
+    /** Run only these axe rule ids. */
+    rules?: string[];
+    /** Skip these axe rule ids. */
+    ignore?: string[];
+}
+/**
+ * Audits `root` (default: the whole page) with axe-core. Needs `axe-core` in the project: `npm i -D axe-core`.
+ * Page-level rules (landmarks, a level-one heading) are skipped when `root` is an element.
+ */
+export declare function a11y(root?: Element, options?: A11yOptions): Promise<{
+    violations: A11yViolation[];
+    ok: boolean;
+}>;
+/** True when `root` has no accessibility violations, so a law can `return await accessible(el)`. */
+export declare function accessible(root?: Element, options?: A11yOptions): Promise<boolean>;
+export { mountComponent, rendersSame, spy } from './component.ts';
+export type { Adapter, Mounted, Rendered } from './component.ts';
+export { allByRole, allByText, allByLabel, allByTestId, byRole, byText, byLabel, byTestId, text, within, } from './queries.ts';
+export type { Matcher, Queries, RoleOptions } from './queries.ts';
+export { domAdapter } from './adapters/dom.ts';
+export type { DomComponent } from './adapters/dom.ts';
+export { elementAdapter } from './adapters/element.ts';
+export type { ElementAdapterOptions } from './adapters/element.ts';
+export { reactAdapter } from './adapters/react.ts';
+export type { ReactFunctions, ReactRootLike } from './adapters/react.ts';
+export { angularAdapter } from './adapters/angular.ts';
+export type { AngularAppRefLike, AngularComponentRefLike, AngularFunctions } from './adapters/angular.ts';
+export interface Timing {
+    runs: number;
+    min: number;
+    median: number;
+    p95: number;
+    max: number;
+}
+/** Times `work` (sync or async) over `runs` runs after a warm-up, in milliseconds as the browser clock reads them. */
+export declare function measure(work: () => unknown, runs?: number): Promise<Timing>;
+/** True when `work` takes at most `budgetMs` at the median, so a law can `return await fast(() => click(add), 50)`. */
+export declare function fast(work: () => unknown, budgetMs: number, runs?: number): Promise<boolean>;
+/** Milliseconds the main thread was blocked by long tasks (over 50 ms) while `work` ran; 0 where the browser has no such API. */
+export declare function blocking(work: () => unknown): Promise<number>;

package/dist/browserApi.js

@@ -0,0 +1,139 @@
+/// <reference lib="dom" />
+// Helpers for laws that run in a browser (`*.browser.laws.ts`). They touch only the DOM, so they work the same with
+// any framework or none: mount your component however you normally do, inside `mount(...)`.
+const registry = () => (globalThis.__tslawsCleanup ??= []);
+/**
+ * A fresh container in the page, removed after the law. Pass markup, a node, or a function that renders into the
+ * container (a framework's `render` call) and may return what undoes it (an `unmount`).
+ */
+export function mount(content) {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    registry().push(() => container.remove());
+    if (typeof content === 'string')
+        container.innerHTML = content;
+    else if (content instanceof Node)
+        container.appendChild(content);
+    else if (typeof content === 'function') {
+        const undo = content(container);
+        if (typeof undo === 'function')
+            registry().push(undo);
+    }
+    return container;
+}
+/** Waits until pending microtasks, timers and animation frames have run, so the DOM has caught up. */
+export async function settle(frames = 2) {
+    await Promise.resolve();
+    await new Promise((done) => setTimeout(done, 0));
+    for (let i = 0; i < frames; i++)
+        await new Promise((done) => requestAnimationFrame(() => done()));
+}
+/** Dispatches a bubbling event. */
+export function fire(target, type, init = {}) {
+    return target.dispatchEvent(new Event(type, { bubbles: true, cancelable: true, ...init }));
+}
+/** A real click: pointer events, then `click`. */
+export function click(target) {
+    const init = { bubbles: true, cancelable: true, composed: true };
+    target.dispatchEvent(new PointerEvent('pointerdown', init));
+    target.dispatchEvent(new MouseEvent('mousedown', init));
+    target.dispatchEvent(new PointerEvent('pointerup', init));
+    target.dispatchEvent(new MouseEvent('mouseup', init));
+    target.dispatchEvent(new MouseEvent('click', init));
+}
+/** Sets a field's value the way typing does, so frameworks that track `input` events notice. */
+export function type(field, text) {
+    const proto = Object.getPrototypeOf(field);
+    Object.getOwnPropertyDescriptor(proto, 'value')?.set?.call(field, text);
+    fire(field, 'input');
+    fire(field, 'change');
+}
+// Rules about a whole page, which an element on its own cannot satisfy.
+const pageRules = ['region', 'page-has-heading-one', 'landmark-one-main'];
+/**
+ * Audits `root` (default: the whole page) with axe-core. Needs `axe-core` in the project: `npm i -D axe-core`.
+ * Page-level rules (landmarks, a level-one heading) are skipped when `root` is an element.
+ */
+export async function a11y(root, options = {}) {
+    let axe;
+    try {
+        // @ts-ignore axe-core is an optional peer dependency and may not be installed when this file is compiled.
+        const loaded = (await import('axe-core'));
+        axe = (loaded.default ?? loaded);
+        if (typeof axe.run !== 'function')
+            throw new Error('not axe');
+    }
+    catch {
+        throw new Error('a11y() needs axe-core: npm i -D axe-core');
+    }
+    const config = {};
+    if (options.rules !== undefined)
+        config.runOnly = { type: 'rule', values: options.rules };
+    const off = [...(options.ignore ?? []), ...(root !== undefined && options.rules === undefined ? pageRules : [])];
+    if (off.length > 0)
+        config.rules = Object.fromEntries(off.map((id) => [id, { enabled: false }]));
+    const results = await axe.run(root ?? document, config);
+    const violations = results.violations.map((v) => ({
+        id: v.id,
+        impact: v.impact ?? null,
+        help: v.help,
+        nodes: v.nodes.map((n) => (n.html.length > 200 ? `${n.html.slice(0, 197)}...` : n.html)),
+    }));
+    return { violations, ok: violations.length === 0 };
+}
+/** True when `root` has no accessibility violations, so a law can `return await accessible(el)`. */
+export async function accessible(root, options) {
+    return (await a11y(root, options)).ok;
+}
+// Component-level testing: isolated mounting with generated props, framework adapters and queries.
+export { mountComponent, rendersSame, spy } from "./component.js";
+export { allByRole, allByText, allByLabel, allByTestId, byRole, byText, byLabel, byTestId, text, within, } from "./queries.js";
+export { domAdapter } from "./adapters/dom.js";
+export { elementAdapter } from "./adapters/element.js";
+export { reactAdapter } from "./adapters/react.js";
+export { angularAdapter } from "./adapters/angular.js";
+/** Times `work` (sync or async) over `runs` runs after a warm-up, in milliseconds as the browser clock reads them. */
+export async function measure(work, runs = 7) {
+    await settle();
+    await work();
+    const times = [];
+    for (let i = 0; i < runs; i++) {
+        const start = performance.now();
+        await work();
+        await settle(1);
+        times.push(performance.now() - start);
+    }
+    times.sort((a, b) => a - b);
+    const at = (q) => times[Math.min(times.length - 1, Math.floor(q * times.length))] ?? 0;
+    return { runs, min: times[0] ?? 0, median: at(0.5), p95: at(0.95), max: times[times.length - 1] ?? 0 };
+}
+/** True when `work` takes at most `budgetMs` at the median, so a law can `return await fast(() => click(add), 50)`. */
+export async function fast(work, budgetMs, runs = 7) {
+    return (await measure(work, runs)).median <= budgetMs;
+}
+/** Milliseconds the main thread was blocked by long tasks (over 50 ms) while `work` ran; 0 where the browser has no such API. */
+export async function blocking(work) {
+    let blocked = 0;
+    const add = (entries) => {
+        for (const entry of entries)
+            blocked += Math.max(0, entry.duration - 50);
+    };
+    let observer;
+    try {
+        observer = new PerformanceObserver((list) => add(list.getEntries()));
+        observer.observe({ type: 'longtask' });
+    }
+    catch {
+        observer = undefined;
+    }
+    // A task of its own, so that `work` is measured as a task and not as part of the caller's.
+    await new Promise((done, fail) => setTimeout(() => {
+        Promise.resolve(work()).then(() => done(), fail);
+    }, 0));
+    await settle();
+    // takeRecords flushes the entries the browser has queued for the observer, so there is nothing to wait for.
+    if (observer !== undefined)
+        add(observer.takeRecords());
+    observer?.disconnect();
+    return blocked;
+}

package/dist/bundled.d.ts

@@ -0,0 +1,17 @@
+export interface Platform {
+    name: string;
+    os: string;
+    cpu: string;
+    libc?: 'glibc' | 'musl';
+}
+export declare const platforms: Platform[];
+export declare const packageName: (platform: Platform) => string;
+export declare const executableName: (os?: string) => string;
+/** The platform of this process, or undefined when there is no compiler build for it. */
+export declare function hostPlatform(): Platform | undefined;
+/** The compiler installed as an optional dependency of tslaws, when there is one for this machine. */
+export declare function bundledCompiler(): string | undefined;
+/** The compiler built in a checkout of the tsc-laws repository (packages/tsc-ts/dist), found by walking up from `from`. */
+export declare function checkoutCompiler(from: string): string | undefined;
+/** The version of this package, for messages. */
+export declare function ownVersion(): string;