reflection-check 0.0.1

package/dist/commands/run.js

@@ -0,0 +1,168 @@
+import { CommanderError } from 'commander';
+import { availableParallelism } from 'node:os';
+import { basename, join } from 'node:path';
+import { runBrowserContract } from '../contracts/browser/browser-contract.js';
+import { runComponentVisualContract } from '../contracts/component/component-visual-contract.js';
+import { runDesignContract } from '../contracts/design/design-contract.js';
+import { createArtifactStore } from '../core/artifact-store.js';
+import { isRunMode, loadReflectionConfig } from '../core/config.js';
+import { ExitCode } from '../core/exit-codes.js';
+import { createRunManifest } from '../core/manifest.js';
+import { createReport, deriveExitCode } from '../core/report-schema.js';
+import { writeReports } from '../core/report-writer.js';
+import { startManagedServer } from '../core/server-manager.js';
+export function parseRunMode(value) {
+    if (!isRunMode(value)) {
+        throw new CommanderError(ExitCode.InvalidUsage, 'reflection.invalidMode', `Invalid mode "${value}". Expected one of: smoke, design, visual, full.`);
+    }
+    return value;
+}
+export async function runCommand(options) {
+    let mode;
+    try {
+        mode = parseRunMode(options.mode);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        throw error;
+    }
+    let config;
+    if (options.config) {
+        try {
+            config = await loadReflectionConfig(options.config);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message);
+            throw new CommanderError(ExitCode.ToolOrConfigError, 'reflection.config', message);
+        }
+    }
+    const startedAt = new Date();
+    const runId = createRunId(startedAt);
+    const ci = options.ci === true;
+    const rootDir = options.reportDir ?? (ci ? 'artifacts/reflection' : '.reflection');
+    let workers;
+    try {
+        workers = resolveWorkerCount(options.workers, ci);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        throw error;
+    }
+    const store = await createArtifactStore({ rootDir, runId });
+    const checks = [];
+    let server;
+    try {
+        const browserConfig = config?.contracts.browser;
+        const designConfig = config?.contracts.design;
+        const componentConfig = config?.contracts.component;
+        const shouldRunBrowser = (mode === 'smoke' || mode === 'full') && browserConfig?.enabled !== false && browserConfig !== undefined;
+        const shouldRunDesign = (mode === 'design' || mode === 'full') && designConfig?.enabled !== false && designConfig !== undefined;
+        const shouldRunComponent = (mode === 'visual' || mode === 'full') && componentConfig?.enabled !== false && componentConfig !== undefined;
+        if (shouldRunBrowser) {
+            if (browserConfig.server) {
+                server = await startManagedServer(browserConfig.server, {
+                    cwd: process.cwd(),
+                    logPath: store.resolveRunPath('server/app.log')
+                });
+            }
+            checks.push(await createEnvironmentCheck(mode, server));
+            checks.push(...(await runBrowserContract(browserConfig, store)));
+        }
+        if (shouldRunDesign) {
+            checks.push(...(await runDesignContract(designConfig, store)));
+        }
+        if (shouldRunComponent) {
+            checks.push(...(await runComponentVisualContract(componentConfig, store)));
+        }
+        if (!shouldRunBrowser && !shouldRunDesign && !shouldRunComponent) {
+            checks.push(...createPhasePlaceholderChecks(mode));
+        }
+    }
+    finally {
+        await server?.stop();
+    }
+    const finishedAt = new Date();
+    const report = createReport({
+        runId,
+        project: config?.project ?? basename(process.cwd()),
+        startedAt,
+        finishedAt,
+        mode,
+        ci,
+        environment: {
+            profile: ci ? 'ci' : 'local',
+            platform: process.platform,
+            nodeVersion: process.version,
+            workers
+        },
+        checks,
+        suggestedNextSteps: [{ kind: 'implementation', summary: 'Implement the next contract runner phase.' }]
+    });
+    const reportArtifacts = await writeReports(store, report);
+    const manifest = createRunManifest({ report: { ...report, artifacts: reportArtifacts }, files: reportArtifacts });
+    await store.writeJson('manifest.json', manifest);
+    console.log('Reflection');
+    console.log('');
+    for (const check of checks) {
+        const icon = check.status === 'pass' ? '✓' : check.status === 'fail' ? '✕' : check.status === 'warn' ? '⚠' : '-';
+        console.log(`${icon} ${check.id}`);
+    }
+    console.log('');
+    console.log(`Status: ${report.status}`);
+    console.log(`Report: ${join(rootDir, 'runs', runId, 'report.md')}`);
+    const exitCode = deriveExitCode(report.status);
+    if (exitCode !== ExitCode.Success) {
+        throw new CommanderError(exitCode, 'reflection.run', `Reflection finished with status: ${report.status}`);
+    }
+}
+function createRunId(date) {
+    const stamp = date.toISOString().replaceAll(':', '-').replace(/\.\d{3}Z$/, 'Z');
+    return `${stamp}-local`;
+}
+function resolveWorkerCount(value, ci) {
+    if (value === undefined) {
+        return ci ? 1 : Math.max(1, Math.min(4, availableParallelism()));
+    }
+    if (value === true || value === false) {
+        throw new CommanderError(ExitCode.InvalidUsage, 'reflection.invalidWorkers', `Invalid workers "${String(value)}". Expected a positive integer.`);
+    }
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || (typeof value === 'string' && !/^[1-9]\d*$/.test(value))) {
+        throw new CommanderError(ExitCode.InvalidUsage, 'reflection.invalidWorkers', `Invalid workers "${value}". Expected a positive integer.`);
+    }
+    return parsed;
+}
+async function createEnvironmentCheck(mode, server) {
+    return {
+        id: `environment.${mode}.server`,
+        suite: 'environment',
+        target: server?.readyUrl ?? 'external-browser-target',
+        status: 'pass',
+        severity: 'info',
+        summary: server ? `Browser target server ready at ${server.readyUrl}.` : 'Browser target uses configured base URL without managed server.',
+        artifacts: [],
+        metadata: {
+            serverStarted: server?.started ?? false,
+            serverReused: server?.reused ?? false,
+            pid: server?.pid
+        }
+    };
+}
+function createPhasePlaceholderChecks(mode) {
+    return [
+        {
+            id: `environment.${mode}.phase-placeholder`,
+            suite: 'environment',
+            target: mode,
+            status: 'pass',
+            severity: 'info',
+            summary: 'Phase 1.2 artifact/report pipeline is available; real contract runners come next.',
+            artifacts: [],
+            metadata: {}
+        }
+    ];
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/run.js.map

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

package/dist/commands/update.d.ts

@@ -0,0 +1,11 @@
+export type UpdateCommandOptions = {
+    config?: string;
+    reportDir?: string;
+    fromRun?: string;
+    route?: string;
+    case?: string;
+    all?: boolean;
+    dryRun?: boolean;
+    ci?: boolean;
+};
+export declare function updateCommand(options?: UpdateCommandOptions): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,183 @@
+import { copyFile, lstat, mkdir, readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { CommanderError } from 'commander';
+import { createBaselineStore } from '../core/baseline-store.js';
+import { loadReflectionConfig } from '../core/config.js';
+import { ExitCode } from '../core/exit-codes.js';
+import { validateReport } from '../core/report-schema.js';
+export async function updateCommand(options = {}) {
+    try {
+        if (options.ci === true || isTruthyCi(process.env.CI)) {
+            throw new CommanderError(ExitCode.ToolOrConfigError, 'reflection.update', 'Reflection update refuses to mutate baselines in CI mode.');
+        }
+        if (!options.route && !options.case && options.all !== true) {
+            throw new CommanderError(ExitCode.InvalidUsage, 'reflection.update', 'Specify --route, --case, or --all before updating baselines.');
+        }
+        if (options.all === true && (options.route || options.case)) {
+            throw new CommanderError(ExitCode.InvalidUsage, 'reflection.update', 'Use --all by itself, or target a specific --route/--case.');
+        }
+        const config = await loadReflectionConfig(options.config ?? 'reflection.config.ts');
+        const reportRoot = resolve(options.reportDir ?? '.reflection');
+        const runsDir = resolve(reportRoot, 'runs');
+        const runId = options.fromRun === undefined || options.fromRun === 'latest' ? await readLatestRunId(reportRoot) : options.fromRun;
+        assertSafeRunId(runId);
+        const runDir = resolve(runsDir, runId);
+        ensureInside(runsDir, runDir);
+        await ensureRealPathInside(runsDir, runDir);
+        const reportPath = resolve(runDir, 'report.json');
+        ensureInside(runDir, reportPath);
+        await ensureRealPathInside(runDir, reportPath);
+        const report = validateReport(JSON.parse(await readFile(reportPath, 'utf8')));
+        if (report.runId !== runId) {
+            throw new Error(`Report run id mismatch: expected ${runId}, found ${report.runId}`);
+        }
+        const plan = await createUpdatePlan({ config, report, runDir, route: options.route, caseId: options.case, all: options.all === true });
+        if (plan.length === 0) {
+            throw new Error('No matching visual baseline updates found for the selected target.');
+        }
+        for (const item of plan) {
+            if (options.dryRun !== true) {
+                await ensureBaselineDestinationInside(item.baselineRoot, item.baselinePath);
+                await mkdir(dirname(item.baselinePath), { recursive: true });
+                await copyFile(item.sourcePath, item.baselinePath);
+            }
+        }
+        console.log(renderUpdateSummary(plan, options.dryRun === true));
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CommanderError(ExitCode.ToolOrConfigError, 'reflection.update', message);
+    }
+}
+async function createUpdatePlan(input) {
+    const visualCases = input.config.contracts.browser?.visualSmoke ?? [];
+    const selectedCases = visualCases.filter((visualCase) => {
+        if (input.all) {
+            return true;
+        }
+        if (input.caseId && visualCase.id !== input.caseId) {
+            return false;
+        }
+        if (input.route && visualCase.route !== input.route) {
+            return false;
+        }
+        return true;
+    });
+    const plan = [];
+    for (const visualCase of selectedCases) {
+        const check = findVisualCheck(input.report, visualCase.id);
+        const actualArtifact = check.artifacts.find((artifact) => artifact.role === 'actual' && artifact.path.endsWith('.png'));
+        if (!actualArtifact) {
+            throw new Error(`Visual check ${check.id} has no actual PNG artifact to promote.`);
+        }
+        const sourcePath = resolve(input.runDir, actualArtifact.path);
+        ensureInside(input.runDir, sourcePath);
+        await ensureRealPathInside(input.runDir, sourcePath);
+        const baselineStore = createBaselineStore(visualCase.baselineRoot ? { rootDir: visualCase.baselineRoot } : {});
+        plan.push({
+            checkId: check.id,
+            caseId: visualCase.id,
+            routeId: visualCase.route,
+            sourcePath,
+            baselineRoot: baselineStore.rootDir,
+            baselinePath: baselineStore.resolveBaselinePath(visualCase.baseline)
+        });
+    }
+    return plan;
+}
+function findVisualCheck(report, caseId) {
+    const check = report.checks.find((candidate) => candidate.id === `visual.${caseId}` && candidate.suite === 'visual');
+    if (!check) {
+        throw new Error(`No visual check found in report for case ${caseId}.`);
+    }
+    return check;
+}
+async function readLatestRunId(rootDir) {
+    const latestPath = resolve(rootDir, 'runs', 'latest');
+    const runsDir = resolve(rootDir, 'runs');
+    ensureInside(runsDir, latestPath);
+    await ensureRealPathInside(runsDir, latestPath);
+    const value = (await readFile(latestPath, 'utf8')).trim();
+    if (value.length === 0) {
+        throw new Error(`Latest Reflection run pointer is empty: ${latestPath}`);
+    }
+    return value;
+}
+function renderUpdateSummary(plan, dryRun) {
+    const lines = ['Reflection update', '', `Dry run: ${dryRun ? 'yes' : 'no'}`, ''];
+    lines.push(dryRun ? 'Would update:' : 'Updated:');
+    for (const item of plan) {
+        lines.push(`- ${item.checkId}: ${relative(process.cwd(), item.sourcePath)} -> ${relative(process.cwd(), item.baselinePath)}`);
+    }
+    return lines.join('\n');
+}
+function assertSafeRunId(runId) {
+    if (!/^[A-Za-z0-9._:-]+$/.test(runId) || isAbsolute(runId) || runId.split(/[\\/]/).includes('..')) {
+        throw new Error(`Invalid Reflection run id: ${runId}`);
+    }
+}
+function isTruthyCi(value) {
+    return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+}
+async function ensureBaselineDestinationInside(baselineRoot, baselinePath) {
+    ensureInside(baselineRoot, baselinePath);
+    const realRoot = await realpath(baselineRoot);
+    await ensureDirectoryInsideBaselineRoot(baselineRoot, dirname(baselinePath), realRoot);
+    try {
+        const stats = await lstat(baselinePath);
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Refusing to overwrite symlinked baseline path: ${baselinePath}`);
+        }
+        const realDestination = await realpath(baselinePath);
+        ensureInside(realRoot, realDestination);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+}
+async function ensureDirectoryInsideBaselineRoot(baselineRoot, directoryPath, realRoot) {
+    ensureInside(baselineRoot, directoryPath);
+    const relativeDirectory = relative(baselineRoot, directoryPath);
+    if (relativeDirectory === '') {
+        return;
+    }
+    let current = baselineRoot;
+    for (const segment of relativeDirectory.split(/[\\/]+/).filter(Boolean)) {
+        current = resolve(current, segment);
+        try {
+            const stats = await lstat(current);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`Refusing to create baseline directory through symlink: ${current}`);
+            }
+            if (!stats.isDirectory()) {
+                throw new Error(`Refusing to create baseline directory through non-directory path: ${current}`);
+            }
+            ensureInside(realRoot, await realpath(current));
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                await mkdir(current);
+                ensureInside(realRoot, await realpath(current));
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+async function ensureRealPathInside(parent, child) {
+    const [realParent, realChild] = await Promise.all([realpath(parent), realpath(child)]);
+    ensureInside(realParent, realChild);
+}
+function ensureInside(parent, child) {
+    const relation = relative(parent, child);
+    if (relation.startsWith('..') || isAbsolute(relation)) {
+        throw new Error(`Refusing to update baselines using a path outside the expected directory: ${child}`);
+    }
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/update.js.map

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

package/dist/contracts/browser/assertions.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from 'playwright';
+export type BrowserExpectation = {
+    urlIncludes: string;
+} | {
+    urlEquals: string;
+} | {
+    role: string;
+    name?: string | undefined;
+} | {
+    label: string;
+} | {
+    text: string;
+} | {
+    noText: string;
+} | {
+    selector: string;
+} | {
+    elementVisible: string;
+} | {
+    elementNotVisible: string;
+} | {
+    noHorizontalOverflow: true;
+} | {
+    noConsoleErrors: true;
+} | {
+    screenshot: string;
+};
+export type AssertionFailure = {
+    classification: string;
+    summary: string;
+    details?: string;
+};
+export declare function evaluateExpectation(page: Page, expectation: BrowserExpectation, consoleErrors: string[]): Promise<AssertionFailure | undefined>;
+export declare function shouldCaptureScreenshot(expectations: BrowserExpectation[]): boolean;

package/dist/contracts/browser/assertions.js

@@ -0,0 +1,87 @@
+import { getHorizontalOverflow } from './overflow-check.js';
+export async function evaluateExpectation(page, expectation, consoleErrors) {
+    if ('screenshot' in expectation) {
+        return undefined;
+    }
+    if ('urlIncludes' in expectation) {
+        if (!page.url().includes(expectation.urlIncludes)) {
+            return { classification: 'route-failure', summary: `Expected URL to include ${expectation.urlIncludes}.`, details: page.url() };
+        }
+        return undefined;
+    }
+    if ('urlEquals' in expectation) {
+        if (page.url() !== expectation.urlEquals) {
+            return { classification: 'route-failure', summary: `Expected URL to equal ${expectation.urlEquals}.`, details: page.url() };
+        }
+        return undefined;
+    }
+    if ('role' in expectation) {
+        const locator = page.getByRole(expectation.role, expectation.name ? { name: expectation.name } : undefined);
+        if ((await locator.count()) === 0) {
+            return { classification: 'dom-contract-failure', summary: `Expected role ${expectation.role}${expectation.name ? ` named ${expectation.name}` : ''}.` };
+        }
+        return undefined;
+    }
+    if ('label' in expectation) {
+        if ((await page.getByLabel(expectation.label).count()) === 0) {
+            return { classification: 'dom-contract-failure', summary: `Expected label ${expectation.label}.` };
+        }
+        return undefined;
+    }
+    if ('text' in expectation) {
+        if ((await page.getByText(expectation.text).count()) === 0) {
+            return { classification: 'dom-contract-failure', summary: `Expected text ${expectation.text}.` };
+        }
+        return undefined;
+    }
+    if ('noText' in expectation) {
+        if ((await page.getByText(expectation.noText).count()) > 0) {
+            return { classification: 'dom-contract-failure', summary: `Unexpected text ${expectation.noText}.` };
+        }
+        return undefined;
+    }
+    if ('selector' in expectation) {
+        if ((await page.locator(expectation.selector).count()) === 0) {
+            return { classification: 'dom-contract-failure', summary: `Expected selector ${expectation.selector}.` };
+        }
+        return undefined;
+    }
+    if ('elementVisible' in expectation) {
+        if (!(await page.locator(expectation.elementVisible).first().isVisible().catch(() => false))) {
+            return { classification: 'dom-contract-failure', summary: `Expected visible element ${expectation.elementVisible}.` };
+        }
+        return undefined;
+    }
+    if ('elementNotVisible' in expectation) {
+        if (await page.locator(expectation.elementNotVisible).first().isVisible().catch(() => false)) {
+            return { classification: 'dom-contract-failure', summary: `Expected hidden or absent element ${expectation.elementNotVisible}.` };
+        }
+        return undefined;
+    }
+    if ('noHorizontalOverflow' in expectation) {
+        const overflow = await getHorizontalOverflow(page);
+        if (overflow.hasOverflow) {
+            return {
+                classification: 'layout-overflow',
+                summary: `Page has horizontal overflow: scroll width ${overflow.scrollWidth}px exceeds viewport ${overflow.viewportWidth}px.`,
+                details: JSON.stringify(overflow)
+            };
+        }
+        return undefined;
+    }
+    if ('noConsoleErrors' in expectation) {
+        if (consoleErrors.length > 0) {
+            return {
+                classification: 'console-error',
+                summary: `Page emitted ${consoleErrors.length} console error${consoleErrors.length === 1 ? '' : 's'}.`,
+                details: consoleErrors.join('\n')
+            };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+export function shouldCaptureScreenshot(expectations) {
+    return expectations.some((expectation) => 'screenshot' in expectation);
+}
+//# sourceMappingURL=assertions.js.map

package/dist/contracts/browser/assertions.js.map

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

package/dist/contracts/browser/browser-contract.d.ts

@@ -0,0 +1,13 @@
+import type { ArtifactStore } from '../../core/artifact-store.js';
+import type { CheckResult } from '../../core/report-schema.js';
+import type { RouteVisualBaselineCase } from '../visual/baseline-compare.js';
+import { type BrowserRoute } from './route-runner.js';
+export type BrowserContractConfig = {
+    enabled?: boolean;
+    blocking?: boolean;
+    baseUrl: string;
+    routes: BrowserRoute[];
+    visualSmoke?: RouteVisualBaselineCase[];
+    maskSelectors?: string[];
+};
+export declare function runBrowserContract(config: BrowserContractConfig, store: ArtifactStore): Promise<CheckResult[]>;

package/dist/contracts/browser/browser-contract.js

@@ -0,0 +1,35 @@
+import { launchBrowser } from '../../integrations/playwright/browser-manager.js';
+import { runRouteVisualSmoke } from '../visual/visual-contract.js';
+import { runBrowserRoute } from './route-runner.js';
+export async function runBrowserContract(config, store) {
+    if (config.enabled === false) {
+        return [];
+    }
+    const browser = await launchBrowser();
+    const checks = [];
+    try {
+        for (const route of config.routes) {
+            for (const viewport of route.viewports) {
+                checks.push(await runBrowserRoute({
+                    browser,
+                    store,
+                    baseUrl: config.baseUrl,
+                    route,
+                    viewport,
+                    blocking: config.blocking ?? true,
+                    maskSelectors: config.maskSelectors ?? []
+                }));
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    checks.push(...(await runRouteVisualSmoke({
+        visualSmoke: config.visualSmoke,
+        browserChecks: checks,
+        store
+    })));
+    return checks;
+}
+//# sourceMappingURL=browser-contract.js.map

package/dist/contracts/browser/browser-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-contract.js","sourceRoot":"","sources":["../../../src/contracts/browser/browser-contract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,kDAAkD,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE,OAAO,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAC;AAWvE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAA6B,EAAE,KAAoB;IAC1F,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,aAAa,EAAE,CAAC;IACtC,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,IAAI,CAAC;QACH,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvC,MAAM,CAAC,IAAI,CACT,MAAM,eAAe,CAAC;oBACpB,OAAO;oBACP,KAAK;oBACL,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,KAAK;oBACL,QAAQ;oBACR,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;oBACjC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;iBAC1C,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,IAAI,CACT,GAAG,CAAC,MAAM,mBAAmB,CAAC;QAC5B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,aAAa,EAAE,MAAM;QACrB,KAAK;KACN,CAAC,CAAC,CACJ,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/contracts/browser/console-observer.d.ts

@@ -0,0 +1,6 @@
+import type { Page } from 'playwright';
+export type ConsoleErrorObserver = {
+    errors: string[];
+    dispose: () => void;
+};
+export declare function observeConsoleErrors(page: Page): ConsoleErrorObserver;

package/dist/contracts/browser/console-observer.js

@@ -0,0 +1,14 @@
+export function observeConsoleErrors(page) {
+    const errors = [];
+    const handler = (message) => {
+        if (message.type() === 'error') {
+            errors.push(message.text());
+        }
+    };
+    page.on('console', handler);
+    return {
+        errors,
+        dispose: () => page.off('console', handler)
+    };
+}
+//# sourceMappingURL=console-observer.js.map

package/dist/contracts/browser/console-observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-observer.js","sourceRoot":"","sources":["../../../src/contracts/browser/console-observer.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,oBAAoB,CAAC,IAAU;IAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,CAAC,OAA2C,EAAE,EAAE;QAC9D,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAE5B,OAAO;QACL,MAAM;QACN,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/dist/contracts/browser/overflow-check.d.ts

@@ -0,0 +1,6 @@
+import type { Page } from 'playwright';
+export declare function getHorizontalOverflow(page: Page): Promise<{
+    hasOverflow: boolean;
+    viewportWidth: number;
+    scrollWidth: number;
+}>;

package/dist/contracts/browser/overflow-check.js

@@ -0,0 +1,15 @@
+export async function getHorizontalOverflow(page) {
+    return page.evaluate(() => {
+        const global = globalThis;
+        const root = global.document.documentElement;
+        const body = global.document.body;
+        const viewportWidth = global.innerWidth;
+        const scrollWidth = Math.max(root.scrollWidth, body?.scrollWidth ?? 0);
+        return {
+            hasOverflow: scrollWidth > viewportWidth + 1,
+            viewportWidth,
+            scrollWidth
+        };
+    });
+}
+//# sourceMappingURL=overflow-check.js.map

package/dist/contracts/browser/overflow-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-check.js","sourceRoot":"","sources":["../../../src/contracts/browser/overflow-check.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAU;IACpD,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACxB,MAAM,MAAM,GAAG,UAMd,CAAC;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAClC,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC;QACxC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,CAAC,CAAC,CAAC;QAEvE,OAAO;YACL,WAAW,EAAE,WAAW,GAAG,aAAa,GAAG,CAAC;YAC5C,aAAa;YACb,WAAW;SACZ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}