explorbot 0.5.8 → 0.5.10

package/dist/src/ai/quartermaster.js

@@ -1,25 +1,41 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import dedent from 'dedent';
 import { z } from 'zod';
 import { outputPath } from "../config.js";
+import { ariaRefSelector, ariaRefSnapshot, parseAriaRefs } from "../utils/aria-ref.js";
+import { compactAriaSnapshot } from "../utils/aria.js";
 import { createDebug, tag } from "../utils/logger.js";
+import { RulesLoader } from "../utils/rules-loader.js";
 import { isCodeceptToolName } from "../utils/step-analyzer.js";
+import { UX_FOCUS_ATTR, countRunningAnimations, measureUx, renderUxMeasurements, uxProbeArgs } from "../utils/ux-probe.js";
 const debugLog = createDebug('explorbot:quartermaster');
+const UX_RULES = ['ux/accessibility', 'ux/interaction', 'ux/responsive', 'ux/navigation', 'ux/copy', 'ux/forms', 'ux/readability', 'ux/motion', 'ux/charts'];
+const UX_BREAKPOINTS = [768, 375];
+const UX_FOCUS_SELECTOR = `[${UX_FOCUS_ATTR}]`;
+const UX_SETTLE_MS = 400;
+const UX_ARIA_CAP = 8000;
+const UX_SCREENSHOT_TIMEOUT = 5000;
+const UX_MAX_FINDINGS = 6;
+const AGENT_NAME = 'quartermaster';
+const FOCUS_CONTAINER_ROLES = ['main', 'region', 'form', 'dialog', 'alertdialog', 'navigation', 'complementary', 'article', 'table', 'grid', 'tabpanel', 'list', 'group', 'banner', 'contentinfo', 'search'];
 export class Quartermaster {
     provider;
     model;
     outputDir;
     pageAnalyses = new Map();
     unsubscribe = null;
-    explorer = null;
+    explorer;
     pendingAnalyses = [];
-    constructor(provider, options) {
+    constructor(provider, explorer, options) {
         this.provider = provider;
+        this.explorer = explorer;
         this.model = options?.model;
         this.outputDir = outputPath('a11y');
     }
-    start(explorer, stateManager) {
-        this.explorer = explorer;
+    start(stateManager) {
+        if (this.unsubscribe)
+            return;
         mkdirSync(this.outputDir, { recursive: true });
         this.unsubscribe = stateManager.onStateChange((event) => {
             this.onPageChange(event);
@@ -45,24 +61,13 @@ export class Quartermaster {
         this.pendingAnalyses.push(analysisPromise);
     }
     async runAxeAnalysis(state) {
-        const page = this.explorer?.page;
+        const page = this.explorer.page;
         if (!page || !state.hash) {
             debugLog('No page available for axe analysis');
             return;
         }
         try {
-            const { AxeBuilder } = await import('@axe-core/playwright');
-            const results = await new AxeBuilder({ page }).analyze();
-            const violations = results.violations.map((v) => ({
-                id: v.id,
-                impact: v.impact,
-                description: v.description,
-                helpUrl: v.helpUrl,
-                nodes: v.nodes.map((n) => ({
-                    html: n.html,
-                    target: n.target,
-                })),
-            }));
+            const violations = await this.axeViolations(page);
             this.pageAnalyses.set(state.hash, {
                 url: state.url,
                 stateHash: state.hash,
@@ -110,6 +115,22 @@ export class Quartermaster {
             return null;
         }
     }
+    async auditUx(result, context) {
+        const focus = await this.markUxFocus(result, context);
+        tag('step').log(`Auditing UX of ${focus.area}`);
+        try {
+            const evidence = await this.explorer.withPage((page) => this.collectUxEvidence(page));
+            return await this.writeUxReport(result, focus, evidence, context);
+        }
+        finally {
+            await this.explorer
+                .withPage((page) => page.evaluate((attr) => {
+                for (const el of Array.from(document.querySelectorAll(`[${attr}]`)))
+                    el.removeAttribute(attr);
+            }, UX_FOCUS_ATTR))
+                .catch(() => { });
+        }
+    }
     async generateSemanticAnalysis(axeViolations, executions, initialState) {
         const failedExecs = executions.filter((e) => !e.wasSuccessful);
         if (failedExecs.length === 0 && axeViolations.length === 0)
@@ -200,4 +221,228 @@ Focus on what would confuse a real user or caused the agent to make mistakes.`;
         }
         return content;
     }
+    async axeViolations(page, include) {
+        const { AxeBuilder } = await import('@axe-core/playwright');
+        let builder = new AxeBuilder({ page });
+        if (include)
+            builder = builder.include(include);
+        const results = await builder.analyze();
+        return results.violations.map((v) => ({
+            id: v.id,
+            impact: v.impact,
+            description: v.description,
+            helpUrl: v.helpUrl,
+            nodes: v.nodes.map((n) => ({
+                html: n.html,
+                target: n.target,
+            })),
+        }));
+    }
+    async markUxFocus(result, context) {
+        const mark = (locator) => locator
+            .first()
+            .evaluate((el, attr) => el.setAttribute(attr, ''), UX_FOCUS_ATTR)
+            .then(() => true)
+            .catch(() => false);
+        const region = result.overlay;
+        const locateRegion = (page) => {
+            if (region.root)
+                return page.locator(region.root);
+            if (region.xpath)
+                return page.locator(`xpath=${region.xpath}`);
+            const name = region.name || undefined;
+            return page.getByRole('dialog', { name }).or(page.getByRole('alertdialog', { name }));
+        };
+        const regionFocus = { area: region.name || `open ${region.type}`, reason: `it is the ${region.type} open on the page` };
+        if (!context.focus && region.isOpen && (await this.explorer.withPage((page) => mark(locateRegion(page)))))
+            return regionFocus;
+        if (context.focus || context.commands.length) {
+            const picked = await this.pickUxFocus(context, mark);
+            if (picked)
+                return picked;
+        }
+        if (region.isOpen && (await this.explorer.withPage((page) => mark(locateRegion(page)))))
+            return regionFocus;
+        let reason = 'nothing narrower is open or was touched by the session on this page';
+        if (context.focus)
+            reason = `"${context.focus}" matched no single container`;
+        return this.explorer.withPage(async (page) => {
+            if (await mark(page.locator('main, [role="main"]')))
+                return { area: 'main content', reason };
+            await mark(page.locator('body'));
+            return { area: 'whole page', reason: `${reason} and the page has no main landmark` };
+        });
+    }
+    async pickUxFocus(context, mark) {
+        const snapshot = await this.explorer.withPage(ariaRefSnapshot).catch(() => '');
+        const candidates = parseAriaRefs(snapshot).filter((entry) => FOCUS_CONTAINER_ROLES.includes(entry.role));
+        if (!candidates.length)
+            return null;
+        const hints = [];
+        if (context.focus)
+            hints.push(`The developer asked to review: ${context.focus}`);
+        if (context.commands.length)
+            hints.push('Commands the session ran on this page, latest last:', ...context.commands.map((command) => `- ${command}`));
+        const schema = z.object({
+            ref: z.enum(['none', ...candidates.map((entry) => entry.ref)]).describe('ref of the chosen container, or none'),
+            area: z.string().describe('the area named as a user would call it, a few words'),
+        });
+        const prompt = dedent `
+      Pick the page area a developer is working on, so a UX review covers it and nothing else.
+      Choose the smallest container that holds everything the hints point at.
+      Answer none when no listed container fits the hints.
+
+      <hints>
+      ${hints.join('\n')}
+      </hints>
+
+      <containers>
+      ${candidates.map((entry) => `- [${entry.ref}] ${entry.role} "${entry.name}"`).join('\n')}
+      </containers>
+
+      <page_aria>
+      ${snapshot.slice(0, UX_ARIA_CAP)}
+      </page_aria>
+    `;
+        const response = await this.provider.generateObject([{ role: 'user', content: prompt }], schema, this.model, { agentName: AGENT_NAME }).catch(() => null);
+        const ref = response?.object?.ref;
+        if (!ref || ref === 'none')
+            return null;
+        if (!(await this.explorer.withPage((page) => mark(page.locator(ariaRefSelector(ref))))))
+            return null;
+        let reason = 'the session commands on this page act inside it';
+        if (context.focus)
+            reason = `it holds "${context.focus}"`;
+        return { area: response.object.area, reason };
+    }
+    async collectUxEvidence(page) {
+        const evidence = { breakpoints: [], axe: [], notes: [] };
+        evidence.axe = await this.axeViolations(page, UX_FOCUS_SELECTOR).catch((error) => {
+            evidence.notes.push(`axe could not run: ${error.message}`);
+            return [];
+        });
+        const ignoredMotion = await this.animationsIgnoringReducedMotion(page);
+        if (ignoredMotion)
+            evidence.notes.push(`${ignoredMotion} animations in the area keep running when reduced motion is requested`);
+        const width = await page.evaluate(() => window.innerWidth);
+        evidence.breakpoints.push(await this.captureUxBreakpoint(page));
+        const narrower = UX_BREAKPOINTS.filter((breakpoint) => breakpoint < width);
+        if (!narrower.length)
+            return evidence;
+        const viewport = page.viewportSize();
+        if (!viewport) {
+            evidence.notes.push('the browser window has no fixed viewport, so narrower widths were not measured');
+            return evidence;
+        }
+        try {
+            for (const breakpoint of narrower) {
+                await page.setViewportSize({ width: breakpoint, height: viewport.height });
+                await page.waitForTimeout(UX_SETTLE_MS);
+                if ((await page.evaluate(() => window.innerWidth)) !== breakpoint) {
+                    evidence.notes.push(`resizing to ${breakpoint}px had no effect, so that width was not measured`);
+                    continue;
+                }
+                evidence.breakpoints.push(await this.captureUxBreakpoint(page));
+            }
+        }
+        finally {
+            await page.setViewportSize(viewport);
+        }
+        return evidence;
+    }
+    async animationsIgnoringReducedMotion(page) {
+        if (!(await page.evaluate(countRunningAnimations, UX_FOCUS_SELECTOR)))
+            return 0;
+        try {
+            await page.emulateMedia({ reducedMotion: 'reduce' });
+            await page.waitForTimeout(UX_SETTLE_MS);
+            return await page.evaluate(countRunningAnimations, UX_FOCUS_SELECTOR);
+        }
+        finally {
+            await page.emulateMedia({ reducedMotion: null });
+        }
+    }
+    async captureUxBreakpoint(page) {
+        const focus = page.locator(UX_FOCUS_SELECTOR).first();
+        const measurements = await page.evaluate(measureUx, uxProbeArgs(UX_FOCUS_SELECTOR));
+        const aria = await focus.ariaSnapshot().catch(() => '');
+        const breakpoint = { measurements, aria: compactAriaSnapshot(aria, true).slice(0, UX_ARIA_CAP) };
+        if (!this.provider.hasVision())
+            return breakpoint;
+        const screenshot = await focus.screenshot({ timeout: UX_SCREENSHOT_TIMEOUT }).catch(() => null);
+        if (screenshot)
+            breakpoint.screenshot = screenshot.toString('base64');
+        return breakpoint;
+    }
+    async writeUxReport(result, focus, evidence, context) {
+        const url = result.url || '';
+        const rules = [RulesLoader.loadRules(AGENT_NAME, UX_RULES, url), this.provider.getSystemPromptForAgent(AGENT_NAME, url)].filter(Boolean).join('\n\n');
+        const system = dedent `
+      <role>
+      You review the UX of one area of a web page a developer is building right now.
+      The report goes back to that developer, so every finding must point at something they can find in that area.
+      </role>
+
+      <focus>
+      Area under review: ${focus.area}, chosen because ${focus.reason}.
+      Report only on elements inside it. Page-wide header, navigation and footer are out of scope unless they are the area under review.
+      </focus>
+
+      <scope>
+      You see one page of one app, not the app.
+      - Report that a text fails and why. Never propose replacement wording, terminology, tone or language: the app's vocabulary is unknown to you.
+      - Never recommend colors, fonts, spacing values, design tokens or visual style: the project owns its design system.
+      - Sizes, gaps, overflow and contrast come only from <measurements> and <axe>. Never estimate them from a screenshot.
+      - Report only what the evidence shows. A check the evidence cannot settle is skipped, not guessed.
+      </scope>
+
+      <rules>
+      Each rule set carries the priority its findings are reported under.
+
+      ${rules}
+      </rules>
+
+      <output>
+      Markdown, no preamble.
+
+      ## Focus
+      One line: the area reviewed and the widths covered.
+
+      Then one section per priority that has findings, in this order: ## Critical, ## High, ## Medium, ## Low. Omit empty sections.
+      Each finding is one bullet of one sentence, at most 30 words:
+      - **<element as the user sees it>** (<rule set>, <width or "all widths">): <evidence>, <what it costs the user>.
+
+      One bullet per cause: elements failing the same check share a bullet naming at most three of them.
+      Write at most ${UX_MAX_FINDINGS} bullets in total across all sections, most severe first; drop the rest.
+      No fix wording, no rule ids, no list of skipped checks, no summary, no tables.
+      When nothing fails, write the Focus section and the line: No UX issues found in this area.
+      </output>
+    `;
+        const sections = [`<page url="${url}" title="${result.title || ''}"></page>`];
+        if (context.commands.length)
+            sections.push(`<session_commands>\n${context.commands.join('\n')}\n</session_commands>`);
+        sections.push(`<axe>\n${evidence.axe.map((v) => `[${v.impact}] ${v.id}: ${v.description} — ${v.nodes[0]?.html.slice(0, 100) || ''}`).join('\n') || 'no violations'}\n</axe>`);
+        if (evidence.notes.length)
+            sections.push(`<notes>\n${evidence.notes.join('\n')}\n</notes>`);
+        for (const breakpoint of evidence.breakpoints) {
+            const aria = breakpoint.aria || 'the area is not rendered at this width';
+            sections.push(`<breakpoint width="${breakpoint.measurements.width}">\n<measurements>\n${renderUxMeasurements(breakpoint.measurements)}\n</measurements>\n<aria>\n${aria}\n</aria>\n</breakpoint>`);
+        }
+        const shots = evidence.breakpoints.filter((breakpoint) => breakpoint.screenshot);
+        if (!shots.length)
+            sections.push('No screenshots are attached: judge from ARIA and measurements only, and say in Focus that visual checks were not possible.');
+        const content = [{ type: 'text', text: sections.join('\n\n') }];
+        for (const shot of shots) {
+            content.push({ type: 'text', text: `Screenshot of the area at ${shot.measurements.width}px:` });
+            content.push({ type: 'file', mediaType: 'image/png', data: shot.screenshot });
+        }
+        let model = this.model || this.provider.getModelForAgent(AGENT_NAME);
+        if (shots.length)
+            model = this.provider.getVisionModel();
+        const response = await this.provider.chat([
+            { role: 'system', content: system },
+            { role: 'user', content },
+        ], model, { agentName: AGENT_NAME });
+        return response.text;
+    }
 }

package/dist/src/ai/tester.js

@@ -322,8 +322,9 @@ export class Tester extends TaskAgent {
                     return;
                 }
                 if (actionPerformed && !wasSuccessful) {
+                    const noted = new Set(Object.values(task.notes).map((note) => note.message));
                     result?.toolExecutions
-                        ?.filter((execution) => !execution.wasSuccessful && execution.input?.explanation)
+                        ?.filter((execution) => !execution.wasSuccessful && execution.input?.explanation && !noted.has(execution.input.explanation))
                         .forEach((execution) => {
                         task.addNote(`Failed to ${execution.input.explanation} (${execution.toolName})`, TestResult.FAILED);
                     });
@@ -333,8 +334,10 @@ export class Tester extends TaskAgent {
                     return;
                 }
                 if (assertionPerformed) {
-                    const message = result?.toolExecutions?.find((execution) => execution.toolName === 'verify')?.output?.message || '';
-                    task.addNote(message, wasSuccessful ? TestResult.PASSED : TestResult.FAILED);
+                    const passedVerifications = result?.toolExecutions?.filter((execution) => this.ASSERTION_TOOLS.includes(execution.toolName) && execution.wasSuccessful) || [];
+                    for (const execution of passedVerifications)
+                        task.addNote(execution.output?.message || '', TestResult.PASSED);
+                    const message = passedVerifications.at(-1)?.output?.message || '';
                     if (wasSuccessful) {
                         conversation.addUserText(dedent `
                 Assertion "${message}" successfully passed!

package/dist/src/commands/init-command.js

@@ -288,6 +288,10 @@ function printInitNextSteps(options) {
     }
     if (options.siteCommands)
         sections.push({ label: 'Explore any site', commands: options.siteCommands });
+    sections.push({
+        label: 'Log in for one run (kept in memory, never saved)',
+        commands: [{ command: `${cli} explore /dashboard --auth 'login: admin@example.com password: secret123'` }],
+    });
     sections.push({
         label: 'Run it from VS Code',
         commands: [{ command: 'https://testomat.ai/explorbot' }],

package/dist/src/commands/options/auth-option.d.ts

@@ -0,0 +1,6 @@
+import { BaseOption } from './base-option.js';
+export declare class AuthOption extends BaseOption {
+    flags: string;
+    description: string;
+    apply(options: Record<string, any>): void;
+}

package/dist/src/commands/options/auth-option.js

@@ -0,0 +1,14 @@
+import { KnowledgeTracker } from '../../knowledge-tracker.js';
+import { registerSecret } from '../../utils/secrets.js';
+import { BaseOption } from './base-option.js';
+export class AuthOption extends BaseOption {
+    flags = '--auth <text>';
+    description = 'Auth details for this run only, not saved to disk, in free form (e.g. "login: admin password: secret" or "Bearer: <token>"). Falls back to EXPLORBOT_AUTH';
+    apply(options) {
+        const auth = options.auth || process.env.EXPLORBOT_AUTH;
+        if (!auth)
+            return;
+        registerSecret(auth);
+        KnowledgeTracker.appendSessionKnowledge(auth);
+    }
+}

package/dist/src/commands/options/index.d.ts

@@ -1,7 +1,9 @@
+import { AuthOption } from './auth-option.js';
 import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export declare const authOption: AuthOption;
 export declare const decisionModelOption: DecisionModelOption;
 export declare const knowledgeOption: KnowledgeOption;
 export declare const wsOption: WsOption;

package/dist/src/commands/options/index.js

@@ -1,7 +1,9 @@
+import { AuthOption } from './auth-option.js';
 import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export const authOption = new AuthOption();
 export const decisionModelOption = new DecisionModelOption();
 export const knowledgeOption = new KnowledgeOption();
 export const wsOption = new WsOption();

package/dist/src/config.js

@@ -50,6 +50,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
     { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
     { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
+    { name: 'EXPLORBOT_AUTH', description: 'Auth details in free form (credentials, a token), kept in memory for the run and never written to disk; same as --auth', secret: true },
     { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
     { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
     { name: 'EXPLORBOT_API_HEADERS', description: 'Headers sent with every API request, one "Name: value" per line', secret: true },

package/dist/src/explorbot.d.ts

@@ -97,7 +97,7 @@ export declare class ExplorBot {
     agentTester(): Tester;
     agentCaptain(): Captain;
     agentExperienceCompactor(): ExperienceCompactor;
-    agentQuartermaster(): Quartermaster | null;
+    agentQuartermaster(): Quartermaster;
     agentHistorian(): Historian;
     agentRerunner(): Rerunner;
     agentDriller(): Driller;

package/dist/src/explorbot.js

@@ -111,6 +111,7 @@ export class ExplorBot {
         if (this.options.optionalAi)
             return this.bootstrapOptionalProvider();
         this.provider = new AIProvider(this.config.ai);
+        this.provider.setJudge(this.judge());
         await this.provider.validateConnection();
     }
     aiFailureReason() {
@@ -217,9 +218,11 @@ export class ExplorBot {
                 const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
                 return new Tester(deps, researcher, navigator, tools);
             });
-            const qm = this.agentQuartermaster();
-            if (qm)
-                this.agents.tester.setQuartermaster(qm);
+            if (this.config.ai?.agents?.quartermaster?.enabled === true) {
+                const quartermaster = this.agentQuartermaster();
+                quartermaster.start(this.stateManager());
+                this.agents.tester.setQuartermaster(quartermaster);
+            }
             if (this.isHistorianEnabled())
                 this.agents.tester.setHistorian(this.agentHistorian());
             this.agents.tester.setPilot(this.agentPilot());
@@ -240,16 +243,7 @@ export class ExplorBot {
         return (this.agents.experienceCompactor ||= new ExperienceCompactor(this.provider, this.experienceTracker()));
     }
     agentQuartermaster() {
-        const config = this.config.ai?.agents?.quartermaster;
-        if (config?.enabled !== true)
-            return null;
-        if (!this.agents.quartermaster) {
-            this.agents.quartermaster = new Quartermaster(this.provider, {
-                model: config?.model,
-            });
-            this.agents.quartermaster.start(this.explorer, this.stateManager());
-        }
-        return this.agents.quartermaster;
+        return (this.agents.quartermaster ||= new Quartermaster(this.provider, this.explorer, { model: this.config.ai?.agents?.quartermaster?.model }));
     }
     agentHistorian() {
         return (this.agents.historian ||= this.createAgent(({ ai, explorer, config, stateManager, playwrightRecorder }) => {
@@ -500,6 +494,7 @@ export class ExplorBot {
     async bootstrapOptionalProvider() {
         try {
             const provider = new AIProvider(this.config.ai);
+            provider.setJudge(this.judge());
             await provider.validateConnection();
             this.provider = provider;
         }

package/dist/src/explorer.js

@@ -74,6 +74,7 @@ class Explorer {
             throw new Error('Playwright helper not available');
         }
         this.applyBasePathToHelper();
+        codeceptjs.store.visibleLocator = this.playwrightHelper.options?.visibleLocator;
         await this.connectOrLaunchBrowser();
         const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
         await this.openContextPage();

package/dist/src/global-config.js

@@ -13,6 +13,7 @@ import { pathToFileURL } from 'node:url';
 import dedent from 'dedent';
 const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
 const SITE_DIRS = ['knowledge', 'experience', 'output'];
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
 export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
 export function globalDir() {
     return join(os.homedir(), '.explorbot');
@@ -33,7 +34,10 @@ export function sitesDir() {
     return join(globalDir(), 'sites');
 }
 export function siteFolderName(url) {
-    return new URL(url).host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
+    const parsed = new URL(url);
+    if (LOOPBACK_HOSTS.includes(parsed.hostname))
+        parsed.hostname = 'localhost';
+    return parsed.host.toLowerCase().replace(/[^a-z0-9._-]/g, '_');
 }
 export function listSites() {
     if (!existsSync(sitesDir()))
@@ -74,7 +78,7 @@ function validateSiteConfig(config, configPath, baseUrl) {
     `);
     }
     const declared = URL.parse(url)?.origin;
-    if (declared === baseUrl)
+    if (declared && siteFolderName(declared) === siteFolderName(baseUrl))
         return;
     throw new Error(dedent `
     Site config declares a different site.

package/dist/src/utils/ux-probe.d.ts

@@ -0,0 +1,25 @@
+export declare const UX_FOCUS_ATTR = "data-explorbot-ux";
+declare const UX_LIMITS: {
+    touchTarget: number;
+    pointerTarget: number;
+    touchWidth: number;
+    targetGap: number;
+    minFontSize: number;
+    minLineHeight: number;
+    maxEntries: number;
+    minOpacity: 0.1;
+};
+export declare function uxProbeArgs(scope: string): UxProbeArgs;
+export declare function renderUxMeasurements(measurements: UxMeasurements): string;
+export declare function measureUx({ scope, controlsSelector, limits }: UxProbeArgs): UxMeasurements;
+export declare function countRunningAnimations(scope: string): number;
+interface UxProbeArgs {
+    scope: string;
+    controlsSelector: string;
+    limits: typeof UX_LIMITS;
+}
+export interface UxMeasurements {
+    width: number;
+    checks: Record<string, string[]>;
+}
+export {};