tslaws 0.3.1 → 0.3.2

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/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/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.3.2",
   "description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
   "bin": {
     "tslaws": "bin/tslaws.js"
@@ -69,11 +69,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.3.2",
+    "tslaws-compiler-darwin-x64": "0.3.2",
+    "tslaws-compiler-linux-arm64-gnu": "0.3.2",
+    "tslaws-compiler-linux-x64-gnu": "0.3.2",
+    "tslaws-compiler-win32-x64-msvc": "0.3.2"
   },
   "publishConfig": {
     "access": "public"