tslaws 0.3.1 → 0.4.0

package/README.md

@@ -159,6 +159,7 @@ See [docs/laws.md](../../docs/laws.md#the-dashboard).
 
 `tslaws mutate [files...] [--max N] [--seed N] [--json]` mutation-tests the laws: it mutates the covered code, re-runs the laws against each mutant, and lists the survivors no law caught. It handles `.tsx`/`.jsx` and projects with a lock, and takes the run flags of `check`. See [docs/laws.md](../../docs/laws.md#mutation-testing).
 
+- **Other source formats:** `tslaws.json` `bundlerPlugins` lists esbuild plugin modules (paths relative to the file) that teach the browser bundler formats like `.tsrx`. See [docs/laws.md](../../docs/laws.md#bundler-plugins).
 - **Settings:** `tslaws.json` `runs`, `bound`, `proofTimeoutMs` and `propertyTimeoutMs` set the run defaults; a command line flag beats them. See [docs/laws.md](../../docs/laws.md#settings).
 
 ## Agents cannot move the goalposts

package/dist/browser.js

@@ -2,8 +2,10 @@
 // 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 { delimiter, join, relative as pathRelative, resolve, sep } from 'node:path';
 import { build as bundleWith } from 'esbuild';
+import { explainBundleError, loadBundlerPlugins } from "./bundlerPlugins.js";
+import { readConfig } from "./coverage.js";
 import { chromium, firefox, webkit } from 'playwright-core';
 import { toWire } from "./generators.js";
 import { runProperty, summarise } from "./property.js";
@@ -156,21 +158,70 @@ function projectModulesPlugin(cwd) {
         },
     };
 }
+// The compiler writes only what it compiles to .tslaws/out, so a relative import of any other source file (a `.tsrx`
+// template, a stylesheet, an image) would look for it there. Such an import resolves to the file beside the source.
+function sourceFilesPlugin(cwd) {
+    const out = join(cwd, '.tslaws', 'out');
+    return {
+        name: 'tslaws-source-files',
+        setup(build) {
+            build.onResolve({ filter: /^\.\.?\// }, (args) => {
+                if (args.resolveDir !== out && !args.resolveDir.startsWith(out + sep))
+                    return undefined;
+                const inOut = resolve(args.resolveDir, args.path);
+                if (existsSync(inOut))
+                    return undefined;
+                const source = join(cwd, pathRelative(out, inOut));
+                return existsSync(source) && !source.endsWith('.js') ? { path: source } : undefined;
+            });
+        },
+    };
+}
+const assetExtensions = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.webp',
+    '.avif',
+    '.svg',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.otf',
+    '.eot',
+];
+/** The project's `bundlerPlugins` from tslaws.json come first, so they can claim a format before the built-in resolver. */
 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;
+    const projectPlugins = await loadBundlerPlugins(cwd, readConfig(cwd).bundlerPlugins);
+    try {
+        const result = await bundleWith({
+            plugins: [...projectPlugins, sourceFilesPlugin(cwd), projectModulesPlugin(cwd)],
+            entryPoints: [jsFile],
+            bundle: true,
+            write: false,
+            // Stylesheets a law imports come out as a separate .css file, which needs an output directory to be named.
+            outdir: join(cwd, '.tslaws', 'bundle'),
+            // Images and fonts become data URLs, so a url() in the CSS or an import in the JavaScript needs no file server.
+            loader: Object.fromEntries(assetExtensions.map((extension) => [extension, 'dataurl'])),
+            format: 'iife',
+            globalName: '__lawModule',
+            platform: 'browser',
+            target: 'es2022',
+            absWorkingDir: cwd,
+            logLevel: 'silent',
+            define: { 'process.env.NODE_ENV': '"development"', global: 'globalThis' },
+        });
+        const emitted = (extension) => result.outputFiles
+            .filter((file) => file.path.endsWith(extension))
+            .map((file) => file.text)
+            .join('\n');
+        return { js: emitted('.js'), css: emitted('.css') };
+    }
+    catch (error) {
+        throw explainBundleError(error);
+    }
 }
 /** Runs the counterexample once more, leaves the DOM as it is, and photographs the page. Best effort. */
 async function capture(page, law, args, options) {
@@ -187,7 +238,7 @@ async function capture(page, law, args, options) {
 }
 /** 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 { js: code, css } = 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;
@@ -216,6 +267,9 @@ export async function runBrowserLaw(law, options) {
         : undefined;
     try {
         await page.setContent('<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>');
+        // The stylesheet goes in before the script runs, as a linked one would.
+        if (css !== '')
+            await page.addStyleTag({ content: css });
         await page.addScriptTag({ content: code });
         await page.addScriptTag({ content: harness });
         const call = async (...args) => {

package/dist/browserApi.d.ts

@@ -47,3 +47,16 @@ 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

@@ -92,3 +92,48 @@ 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

@@ -11,5 +11,7 @@ export declare const executableName: (os?: string) => string;
 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;

package/dist/bundled.js

@@ -44,6 +44,17 @@ export function bundledCompiler() {
         return undefined;
     }
 }
+/** The compiler built in a checkout of the tsc-laws repository (packages/tsc-ts/dist), found by walking up from `from`. */
+export function checkoutCompiler(from) {
+    const name = process.platform === 'win32' ? 'tsc.exe' : 'tsc';
+    for (let dir = from;; dir = dirname(dir)) {
+        const candidate = join(dir, 'packages', 'tsc-ts', 'dist', name);
+        if (existsSync(candidate))
+            return candidate;
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
 /** The version of this package, for messages. */
 export function ownVersion() {
     try {

package/dist/bundlerPlugins.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from 'esbuild';
+/** What a plugin factory receives. */
+export interface BundlerPluginContext {
+    /** The project root: the directory holding tslaws.json. */
+    cwd: string;
+}
+export type BundlerPluginExport = Plugin | ((context: BundlerPluginContext) => Plugin | Promise<Plugin>);
+/** The setting the messages name. */
+export declare const bundlerPluginsSetting = "bundlerPlugins";
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export declare function loadBundlerPlugins(cwd: string, paths: readonly string[] | undefined): Promise<Plugin[]>;
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export declare function explainBundleError(error: Error): Error;

package/dist/bundlerPlugins.js

@@ -0,0 +1,71 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Bundler plugins: a project teaches the browser bundler a source format (`.tsrx`, `.svelte`, ...) by listing esbuild
+// plugin modules under `bundlerPlugins` in tslaws.json. Each module default-exports an esbuild Plugin, or a function
+// (sync or async) that takes `{ cwd }` and returns one.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** The setting the messages name. */
+export const bundlerPluginsSetting = 'bundlerPlugins';
+/**
+ * Loads each listed module (paths relative to `cwd`, where tslaws.json lives) with a dynamic import of its file URL.
+ * Throws one error naming the setting and the module when a module is missing, throws while loading or in its
+ * factory, or does not export a plugin, so the law file reports an `error` rather than the run crashing.
+ */
+export async function loadBundlerPlugins(cwd, paths) {
+    const plugins = [];
+    for (const path of paths ?? []) {
+        const file = isAbsolute(path) ? path : resolve(cwd, path);
+        const fail = (why) => {
+            throw new Error(`tslaws.json ${bundlerPluginsSetting}: cannot use "${path}" (${file}): ${why}`);
+        };
+        if (!existsSync(file))
+            fail('no such file; paths are relative to the directory of tslaws.json');
+        let exported;
+        try {
+            exported = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href))).default;
+        }
+        catch (error) {
+            return fail(`it failed to load: ${error.message}`);
+        }
+        let plugin = exported;
+        if (typeof exported === 'function') {
+            try {
+                plugin = await exported({ cwd });
+            }
+            catch (error) {
+                return fail(`its plugin function threw: ${error.message}`);
+            }
+        }
+        const candidate = plugin;
+        if (typeof candidate !== 'object' ||
+            candidate === null ||
+            typeof candidate.name !== 'string' ||
+            typeof candidate.setup !== 'function')
+            fail('its default export must be an esbuild plugin ({ name, setup }) or a function returning one');
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/**
+ * Rewrites an esbuild failure into advice when the cause is a source format the bundler has no loader for (the usual
+ * sign that a `bundlerPlugins` entry is missing). Other messages pass through unchanged.
+ */
+export function explainBundleError(error) {
+    const match = /No loader is configured for "(\.[^"]+)" files/.exec(error.message);
+    if (match === null)
+        return error;
+    const extension = match[1];
+    const advice = `the browser bundler cannot load "${extension}" files. Add a bundler plugin for that extension in tslaws.json ` +
+        `"${bundlerPluginsSetting}", for example { "${bundlerPluginsSetting}": ["./tools/${extension.slice(1)}-plugin.mjs"] }, ` +
+        `where the module default-exports an esbuild plugin whose onLoad({ filter: /\${extension}$/ }) returns the compiled ` +
+        `JavaScript (see "Bundler plugins" in docs/laws.md)`;
+    return new Error(`${advice}. esbuild said: ${error.message.split('\n')[0]}`);
+}

package/dist/cli.js

@@ -2,7 +2,7 @@ import { createInterface } from 'node:readline/promises';
 import { readdirSync, statSync, watch } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { resolveEngine } from "./browser.js";
-import { bundledCompiler } from "./bundled.js";
+import { bundledCompiler, checkoutCompiler } from "./bundled.js";
 import { check, exemptionsOf } from "./check.js";
 import { readManifest } from "./compile.js";
 import { hintFor } from "./hints.js";
@@ -18,7 +18,7 @@ import { serveUi } from "./ui.js";
 import { writeLock } from "./lock.js";
 const usage = `tslaws init [--force]       scaffold tslaws.json, .gitignore, AGENTS.md, Claude Code hooks and a starter law (never writes the lock)
 tslaws check [files...] [--reporter text|json|junit|github] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--no-regressions] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH] [--browser chromium|firefox|webkit]
-tslaws ui [files...] [--port N] [--no-open]   open a dashboard of the laws in a browser: tree, filters, search, source, live reruns on save
+tslaws ui [files...] [--port N] [--no-open] [--tab]   open a dashboard of the laws in its own desktop window (--tab: a browser tab): tree, filters, search, source, live reruns on save
 tslaws mutate [files...] [--max N] [--seed N] [--runs N] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--browser ENGINE] [--json]   mutation-test the laws: mutate covered code, report mutants no law kills
 tslaws regressions [list|clear]   show or delete the stored counterexamples (.tslaws/regressions); check replays them first, --no-regressions skips them
 tslaws accept [files...]     record the current laws in tsc-laws.lock (people only: needs a terminal)
@@ -151,7 +151,7 @@ function options(cwd, flags, chosen) {
         cwd,
         runs: settings.runs,
         seed: flags.has('seed') ? Number(flags.get('seed')) : undefined,
-        compiler: String(flags.get('compiler') ?? process.env.TSC_LAWS_BIN ?? bundledCompiler() ?? 'tsc-laws'),
+        compiler: String(flags.get('compiler') ?? process.env.TSC_LAWS_BIN ?? bundledCompiler() ?? checkoutCompiler(cwd) ?? 'tsc-laws'),
         lockFile: join(cwd, 'tsc-laws.lock'),
         noProve: flags.has('no-prove'),
         noRegressions: flags.has('no-regressions'),
@@ -350,6 +350,7 @@ export async function main(args) {
             cwd,
             port: Number(flags.get('port') ?? 51205),
             open: !flags.has('no-open'),
+            appWindow: !flags.has('tab'),
             // A watcher sees a browser page only if it stays as the law left it for a moment.
             run: (only, onEvent, laws) => check({ ...options(cwd, flags, only ?? chosen), only: laws, onEvent, browserPauseMs: 120 }, !flags.has('proposed')),
             log: (line) => process.stdout.write(`${line}\n`),

package/dist/compile.d.ts

@@ -5,7 +5,6 @@ export interface BuildResult {
     diagnostics: string;
     ok: boolean;
 }
-/** Lists the laws of `files` with the problems that stop them running. */
 export declare function readManifest(compiler: string, files: string[], cwd: string): ManifestLaw[];
 /**
  * The compiler flags for the `compilerOptions` of tslaws.json. Only the supported keys pass; anything else is an

package/dist/compile.js

@@ -36,6 +36,12 @@ function compilerEnv(cwd, compiler) {
     }
 }
 /** Lists the laws of `files` with the problems that stop them running. */
+/** Says what to do when the compiler cannot start, in particular when none was found at all. */
+function cannotRun(compiler, error) {
+    if (error.code === 'ENOENT')
+        return `no tsc-laws compiler found (${compiler}): install the tslaws-compiler package for this platform, or set TSC_LAWS_BIN / --compiler to the compiler executable`;
+    return `cannot run ${compiler}: ${error.message}`;
+}
 export function readManifest(compiler, files, cwd) {
     const run = launch(compiler, ['--laws-manifest', ...files], {
         cwd,
@@ -44,7 +50,7 @@ export function readManifest(compiler, files, cwd) {
         env: compilerEnv(cwd, compiler),
     });
     if (run.error !== undefined)
-        throw new Error(`cannot run ${compiler}: ${run.error.message}`);
+        throw new Error(cannotRun(compiler, run.error));
     const text = (run.stdout ?? '').trim();
     if (text === '')
         throw new Error(`${compiler} --laws-manifest printed nothing: ${run.stderr ?? ''}`);
@@ -131,6 +137,6 @@ export function build(compiler, files, cwd) {
         `${run.stdout ?? ''}${run.stderr ?? ''}`.trim() === ''; attempt += 1)
         run = launch(compiler, args, { cwd, encoding: 'utf8', maxBuffer: 64 << 20, env: compilerEnv(cwd, compiler) });
     if (run.error !== undefined)
-        throw new Error(`cannot run ${compiler}: ${run.error.message}`);
+        throw new Error(cannotRun(compiler, run.error));
     return { outDir, diagnostics: `${run.stdout ?? ''}${run.stderr ?? ''}`.trim(), ok: run.status === 0 };
 }

package/dist/coverage.d.ts

@@ -6,6 +6,8 @@ export interface CoverageConfig {
     compilerOptions?: Record<string, unknown>;
     /** End-to-end laws: the app to drive; see `parseE2eConfig`. */
     e2e?: E2eConfig;
+    /** esbuild plugin modules (paths relative to tslaws.json) that teach the browser bundler new source formats. */
+    bundlerPlugins?: string[];
     /** Run settings; a command line flag beats them and they beat the built-in default. */
     runs?: number;
     propertyTimeoutMs?: number;

package/dist/coverage.js

@@ -9,7 +9,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import ts from 'typescript';
 import { parseE2eConfig } from "./e2e.js";
 const settingKeys = ['runs', 'propertyTimeoutMs', 'proofTimeoutMs', 'bound'];
-const configKeys = ['cover', 'compilerOptions', 'e2e', ...settingKeys];
+const configKeys = ['cover', 'compilerOptions', 'e2e', 'bundlerPlugins', ...settingKeys];
 /** Validates the top level of tslaws.json: known keys only, and the run settings are integers of at least 1. */
 export function parseConfig(raw) {
     const fail = (message) => {
@@ -27,6 +27,10 @@ export function parseConfig(raw) {
         if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1))
             fail(`"${key}" must be an integer of at least 1, got ${JSON.stringify(value)}`);
     }
+    const plugins = object.bundlerPlugins;
+    if (plugins !== undefined &&
+        (!Array.isArray(plugins) || plugins.some((entry) => typeof entry !== 'string' || entry === '')))
+        fail(`"bundlerPlugins" must be an array of module paths, got ${JSON.stringify(plugins)}`);
     return object;
 }
 export function readConfig(cwd) {

package/dist/e2e.js

@@ -208,8 +208,21 @@ async function startServer(server, cwd) {
         throw error;
     }
 }
-/** Runs `law` once in a fresh context; `keep` leaves the page open for a photograph. */
+/** A browser that died under the machine, as opposed to a law that failed. */
+const crashed = /Target (?:page, context or browser has been closed|crashed)|Page crashed|browser has been closed/;
+/** Runs `law` once in a fresh context; `keep` leaves the page open for a photograph. A crashed browser tab is tried again, twice at most. */
 async function runOnce(law, args, contextOf, baseURL, options, track, keep) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await runAttempt(law, args, contextOf, baseURL, options, track, keep);
+        }
+        catch (error) {
+            if (attempt >= 2 || !crashed.test(error instanceof Error ? error.message : String(error)))
+                throw error;
+        }
+    }
+}
+async function runAttempt(law, args, contextOf, baseURL, options, track, keep) {
     const context = await contextOf();
     let closing = true;
     try {

package/dist/e2eApi.d.ts

@@ -46,3 +46,35 @@ export declare function a11y(target?: Page, options?: A11yOptions): Promise<{
 }>;
 /** True when the page has no accessibility violations, so a law can `return await accessible()`. */
 export declare function accessible(target?: Page, options?: A11yOptions): Promise<boolean>;
+/** What the browser measured for the page: the numbers behind Core Web Vitals, plus size. Times are milliseconds. */
+export interface Vitals {
+    /** Time to first contentful paint. */
+    fcp: number | null;
+    /** Largest contentful paint (Chromium). */
+    lcp: number | null;
+    /** Cumulative layout shift, unitless (Chromium). */
+    cls: number;
+    /** Time the main thread was blocked by long tasks beyond 50 ms each (Chromium). */
+    blocking: number;
+    /** DOMContentLoaded and load, from navigation start. */
+    domContentLoaded: number | null;
+    load: number | null;
+    /** Elements in the document. */
+    domNodes: number;
+    /** Bytes transferred for the page and everything it loaded. */
+    bytes: number;
+}
+export type SpeedBudget = Partial<Record<keyof Vitals, number>>;
+/** Measures the page as it stands: paint, layout shift, blocking time, load and size. Call it after `open()` and `settle()`. */
+export declare function vitals(target?: Page): Promise<Vitals>;
+/**
+ * Checks the page against a budget, for example `{ lcp: 2500, cls: 0.1, blocking: 200 }`. `violations` names each measure over its
+ * budget, so an agent sees what to fix; a measure the browser cannot report counts as over.
+ */
+export declare function speed(budget: SpeedBudget, target?: Page): Promise<{
+    vitals: Vitals;
+    violations: string[];
+    ok: boolean;
+}>;
+/** True when the page is within `budget`, so a law can `return await fast({ lcp: 2500 })`. */
+export declare function fast(budget: SpeedBudget, target?: Page): Promise<boolean>;

package/dist/e2eApi.js

@@ -90,3 +90,51 @@ function axeConfig(options) {
 export async function accessible(target, options) {
     return (await a11y(target, options)).ok;
 }
+const vitalsScript = `new Promise((done) => {
+  const out = { fcp: null, lcp: null, cls: 0, blocking: 0 };
+  const watch = (type, onEntry) => {
+    try {
+      new PerformanceObserver((list) => list.getEntries().forEach(onEntry)).observe({ type, buffered: true });
+    } catch {}
+  };
+  watch('paint', (e) => { if (e.name === 'first-contentful-paint') out.fcp = e.startTime; });
+  watch('largest-contentful-paint', (e) => { out.lcp = e.startTime; });
+  watch('layout-shift', (e) => { if (!e.hadRecentInput) out.cls += e.value; });
+  watch('longtask', (e) => { out.blocking += Math.max(0, e.duration - 50); });
+  setTimeout(() => {
+    const nav = performance.getEntriesByType('navigation')[0];
+    const bytes = performance.getEntriesByType('resource').reduce((sum, r) => sum + (r.transferSize || 0), nav ? nav.transferSize || 0 : 0);
+    done({
+      ...out,
+      domContentLoaded: nav ? nav.domContentLoadedEventEnd : null,
+      load: nav && nav.loadEventEnd > 0 ? nav.loadEventEnd : null,
+      domNodes: document.getElementsByTagName('*').length,
+      bytes,
+    });
+  }, 250);
+})`;
+/** Measures the page as it stands: paint, layout shift, blocking time, load and size. Call it after `open()` and `settle()`. */
+export async function vitals(target) {
+    const used = target ?? current().page;
+    return (await used.evaluate(vitalsScript));
+}
+/**
+ * Checks the page against a budget, for example `{ lcp: 2500, cls: 0.1, blocking: 200 }`. `violations` names each measure over its
+ * budget, so an agent sees what to fix; a measure the browser cannot report counts as over.
+ */
+export async function speed(budget, target) {
+    const measured = await vitals(target);
+    const violations = [];
+    for (const [name, limit] of Object.entries(budget)) {
+        const value = measured[name];
+        if (value === null)
+            violations.push(`${name}: not reported (budget ${limit})`);
+        else if (value > limit)
+            violations.push(`${name}: ${Math.round(value * 1000) / 1000} over budget ${limit}`);
+    }
+    return { vitals: measured, violations, ok: violations.length === 0 };
+}
+/** True when the page is within `budget`, so a law can `return await fast({ lcp: 2500 })`. */
+export async function fast(budget, target) {
+    return (await speed(budget, target)).ok;
+}

package/dist/ui.d.ts

@@ -4,6 +4,8 @@ export interface UiOptions {
     cwd: string;
     port: number;
     open: boolean;
+    /** Open in its own chromeless window (Chrome, Edge or Chromium) rather than a tab, so it reads as a desktop app. */
+    appWindow?: boolean;
     /** Runs the check of the project, of just these law files, or (with `laws`, in one file) of just these laws. */
     run: (files: string[] | undefined, onEvent: (event: LawEvent) => void, laws?: string[]) => Promise<CheckReport>;
     log: (line: string) => void;

package/dist/ui.js

@@ -2,7 +2,7 @@
 // status filters and search, a detail pane (report, source, diagnostics), and live reruns when a file changes.
 // It listens on 127.0.0.1 only and offers no way to accept laws: that stays a person's act at a terminal.
 import { spawn } from 'node:child_process';
-import { readFileSync, watch } from 'node:fs';
+import { existsSync, readFileSync, watch } from 'node:fs';
 import { createServer } from 'node:http';
 import { basename, join, resolve, sep } from 'node:path';
 import { hintFor } from "./hints.js";
@@ -29,7 +29,34 @@ function sourceOf(cwd, file) {
         return undefined;
     }
 }
-function openInBrowser(url) {
+/** A Chromium-family browser, which can show the page as an app window. */
+function appBrowser() {
+    const env = process.env;
+    const candidates = process.platform === 'win32'
+        ? [env['ProgramFiles(x86)'], env['ProgramFiles'], env['LOCALAPPDATA']].flatMap((base) => base === undefined
+            ? []
+            : [join(base, 'Microsoft/Edge/Application/msedge.exe'), join(base, 'Google/Chrome/Application/chrome.exe')])
+        : process.platform === 'darwin'
+            ? [
+                '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+                '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+            ]
+            : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/microsoft-edge'];
+    return candidates.find((path) => existsSync(path));
+}
+function openInBrowser(url, appWindow) {
+    const browser = appWindow ? appBrowser() : undefined;
+    if (browser !== undefined) {
+        try {
+            spawn(browser, [`--app=${url}`, '--window-size=1360,860', '--no-first-run'], { stdio: 'ignore', detached: true })
+                .on('error', () => undefined)
+                .unref();
+            return;
+        }
+        catch {
+            // Falls back to the default browser.
+        }
+    }
     const [command, args] = process.platform === 'win32'
         ? ['cmd', ['/c', 'start', '', url]]
         : process.platform === 'darwin'
@@ -276,7 +303,7 @@ export async function serveUi(options) {
     const url = `http://127.0.0.1:${port}/`;
     options.log(`tslaws ui: ${url}  (Ctrl+C exits)`);
     if (options.open)
-        openInBrowser(url);
+        openInBrowser(url, options.appWindow ?? false);
     let timer;
     const watcher = watch(cwd, { recursive: true }, (_event, filename) => {
         const name = filename === null ? null : String(filename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tslaws",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
   "bin": {
     "tslaws": "bin/tslaws.js"
@@ -58,7 +58,9 @@
     "z3-solver": "^4.15.0"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0"
+    "@tsrx/ripple": "0.2.11",
+    "@types/node": "^24.0.0",
+    "ripple": "0.6.1"
   },
   "peerDependencies": {
     "axe-core": "^4.0.0"
@@ -69,11 +71,11 @@
     }
   },
   "optionalDependencies": {
-    "tslaws-compiler-darwin-arm64": "0.3.1",
-    "tslaws-compiler-darwin-x64": "0.3.1",
-    "tslaws-compiler-linux-arm64-gnu": "0.3.1",
-    "tslaws-compiler-linux-x64-gnu": "0.3.1",
-    "tslaws-compiler-win32-x64-msvc": "0.3.1"
+    "tslaws-compiler-darwin-arm64": "0.4.0",
+    "tslaws-compiler-darwin-x64": "0.4.0",
+    "tslaws-compiler-linux-arm64-gnu": "0.4.0",
+    "tslaws-compiler-linux-x64-gnu": "0.4.0",
+    "tslaws-compiler-win32-x64-msvc": "0.4.0"
   },
   "publishConfig": {
     "access": "public"