@blazediff/agent 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+import { BoundingBox, InterpretResult } from '@blazediff/core-native';
+
+type VerdictLabel = "regression-likely" | "intentional-likely" | "noise-likely" | "ambiguous";
+type VerdictAction = "investigate" | "rewrite-if-intended" | "ignore-or-rewrite";
+interface Verdict {
+    label: VerdictLabel;
+    headline: string;
+    rationale: string[];
+    action: VerdictAction;
+}
+
+declare const STABILITY_HOOKS_VERSION = 1;
+interface RegionSummary {
+    bbox: BoundingBox;
+    pixelCount: number;
+    percentage: number;
+    changeType: string;
+    confidence: number;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface WaitForSelector {
+    selector: string;
+    timeoutMs?: number;
+}
+type WaitFor = "networkidle" | "fonts" | WaitForSelector;
+interface ManifestEntry {
+    id: string;
+    url: string;
+    viewport: Viewport;
+    auth: null | "required";
+    waitFor: WaitFor[];
+    mask: string[];
+    fullPage?: boolean;
+    baselinePath: string;
+    captureHash: string;
+    createdBy: "agent" | "human";
+    createdAt: string;
+}
+interface Manifest {
+    version: 1;
+    configHash: string;
+    stabilityHooksVersion: number;
+    entries: ManifestEntry[];
+}
+interface DevServerConfig {
+    command: string;
+    port: number;
+    cwd?: string;
+    readyTimeoutMs?: number;
+}
+interface AgentConfig {
+    devServer: DevServerConfig | null;
+    framework?: string;
+    packageManager?: "npm" | "pnpm" | "yarn" | "bun";
+    baseUrl?: string;
+}
+interface CaptureOptions {
+    id: string;
+    url: string;
+    viewport?: Viewport;
+    mask?: string[];
+    waitFor?: WaitFor[];
+    fullPage?: boolean;
+    mode: "baseline" | "actual";
+}
+interface DiscoveredRoute {
+    url: string;
+    source: "next-manifest" | "sitemap" | "crawl";
+    auth?: "required";
+}
+interface CheckReport {
+    createdAt: string;
+    totalEntries: number;
+    passed: number;
+    failed: number;
+    pendingJudgments: number;
+    results: CheckResult[];
+}
+interface CheckResult {
+    id: string;
+    url: string;
+    status: "pass" | "fail" | "missing-baseline" | "stale-baseline" | "needs-judgment";
+    diffCount?: number;
+    diffPercentage?: number;
+    severity?: string;
+    regions?: RegionSummary[];
+    verdict?: Verdict;
+    diffPath?: string;
+    actualPath?: string;
+    baselinePath?: string;
+    message?: string;
+}
+
+interface CaptureResult {
+    id: string;
+    outputPath: string;
+    mode: "baseline" | "actual";
+    bytes: number;
+}
+declare function captureScreenshot(baseUrl: string, opts: CaptureOptions, cwd?: string): Promise<CaptureResult>;
+
+interface BrowsersInstallOptions {
+    check?: boolean;
+}
+interface BrowsersInstallResult {
+    installed: boolean;
+    executablePath: string | null;
+    cliPath: string;
+}
+declare function installBrowsers(opts?: BrowsersInstallOptions): Promise<BrowsersInstallResult>;
+
+interface CaptureRouteInput {
+    id: string;
+    url: string;
+    mask?: string[];
+    viewport?: Viewport;
+    waitFor?: WaitFor[];
+    fullPage?: boolean;
+    mode?: "baseline" | "actual";
+}
+interface RunCapturesOptions {
+    baseUrl: string;
+    routes: CaptureRouteInput[];
+    mode?: "baseline" | "actual";
+    writeManifest?: boolean;
+    cwd?: string;
+}
+interface CaptureRouteResult {
+    id: string;
+    url: string;
+    mode: "baseline" | "actual";
+    ok: boolean;
+    outputPath?: string;
+    bytes?: number;
+    error?: string;
+}
+interface RunCapturesReport {
+    total: number;
+    succeeded: number;
+    failed: number;
+    manifestUpdates: number;
+    results: CaptureRouteResult[];
+}
+declare function runCaptures(opts: RunCapturesOptions): Promise<RunCapturesReport>;
+
+interface JudgeInput {
+    entry: ManifestEntry;
+    baselinePath: string;
+    actualPath: string;
+    diffPath?: string;
+    regions?: RegionSummary[];
+    diffPercentage?: number;
+    severity?: string;
+    heuristicVerdict: Verdict;
+}
+type JudgmentRequestRegion = RegionSummary;
+type JudgeOutput = {
+    kind: "judged";
+    verdict: Verdict;
+    rationale?: string;
+    confidence?: number;
+} | {
+    kind: "deferred";
+    requestPath: string;
+};
+interface Judge {
+    readonly name: string;
+    judge(input: JudgeInput, cwd: string): Promise<JudgeOutput>;
+}
+type JudgeBackend = "none" | "host";
+
+interface ApplyJudgmentsResult {
+    report: CheckReport;
+    applied: string[];
+    missing: string[];
+    invalid: string[];
+}
+declare function applyJudgments(cwd?: string): Promise<ApplyJudgmentsResult>;
+
+interface JudgmentRequest {
+    id: string;
+    url: string;
+    status: CheckResult["status"];
+    diffPercentage?: number;
+    severity?: string;
+    regions?: RegionSummary[];
+    paths: {
+        baseline?: string;
+        actual?: string;
+        diff?: string;
+        locator?: string;
+        tiles?: string;
+    };
+    heuristicVerdict?: Verdict;
+    manifestEntry: {
+        viewport: ManifestEntry["viewport"];
+        mask: ManifestEntry["mask"];
+        waitFor: ManifestEntry["waitFor"];
+        fullPage?: boolean;
+    };
+    signature: string;
+    message?: string;
+    instructions?: string;
+    createdAt: string;
+}
+
+declare function resolveJudge(backend: JudgeBackend): Judge;
+
+interface CheckOptions {
+    baseUrl: string;
+    cwd?: string;
+    threshold?: number;
+    concurrency?: number;
+    emitDiffPng?: boolean;
+    junitPath?: string;
+    judge?: JudgeBackend;
+}
+declare function runCheck(opts: CheckOptions): Promise<CheckReport>;
+
+declare function loadConfig(cwd?: string): Promise<AgentConfig | null>;
+declare function saveConfig(config: AgentConfig, cwd?: string): Promise<void>;
+declare function configHash(config: AgentConfig): string;
+declare function resolveBaseUrl(config: AgentConfig | null, override?: string): string;
+
+interface DiffOptions {
+    threshold?: number;
+    antialiasing?: boolean;
+    emitDiffPng?: boolean;
+}
+interface DiffOutcome {
+    id: string;
+    baselinePath: string;
+    actualPath: string;
+    diffPath?: string;
+    match: boolean;
+    reason?: "pixel-diff" | "layout-diff" | "file-not-exists";
+    diffCount?: number;
+    diffPercentage?: number;
+    interpretation?: InterpretResult;
+}
+declare function diffEntry(id: string, baselinePath: string, actualPath: string, opts?: DiffOptions, cwd?: string): Promise<DiffOutcome>;
+
+interface DiscoverOptions {
+    baseUrl: string;
+    cwd?: string;
+    maxRoutes?: number;
+    skipCrawl?: boolean;
+}
+declare function discover(opts: DiscoverOptions): Promise<DiscoveredRoute[]>;
+
+interface RunOptions {
+    baseUrl: string;
+    cwd?: string;
+    threshold?: number;
+    concurrency?: number;
+    emitDiffPng?: boolean;
+    junitPath?: string;
+    judge?: JudgeBackend;
+}
+declare function runGraph(opts: RunOptions): Promise<CheckReport>;
+
+declare function loadManifest(cwd?: string): Promise<Manifest | null>;
+declare function saveManifest(manifest: Manifest, cwd?: string): Promise<void>;
+
+declare const paths: (cwd?: string) => {
+    root: string;
+    config: string;
+    manifest: string;
+    baselines: string;
+    actual: string;
+    judgments: string;
+    summary: string;
+    gitignore: string;
+    serverLog: string;
+    serverPid: string;
+};
+
+export { type AgentConfig, type ApplyJudgmentsResult, type BrowsersInstallOptions, type BrowsersInstallResult, type CaptureOptions, type CaptureRouteInput, type CaptureRouteResult, type CheckReport, type CheckResult, type DevServerConfig, type DiffOptions, type DiffOutcome, type DiscoveredRoute, type Judge, type JudgeBackend, type JudgeInput, type JudgeOutput, type JudgmentRequest, type JudgmentRequestRegion, type Manifest, type ManifestEntry, type RegionSummary, type RunCapturesOptions, type RunCapturesReport, type RunOptions, STABILITY_HOOKS_VERSION, type Verdict, type VerdictAction, type VerdictLabel, type Viewport, type WaitFor, type WaitForSelector, applyJudgments, captureScreenshot, configHash, diffEntry, discover, installBrowsers, loadConfig, loadManifest, paths, resolveBaseUrl, resolveJudge, runCaptures, runCheck, runGraph, saveConfig, saveManifest };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { BoundingBox, InterpretResult } from '@blazediff/core-native';
+
+type VerdictLabel = "regression-likely" | "intentional-likely" | "noise-likely" | "ambiguous";
+type VerdictAction = "investigate" | "rewrite-if-intended" | "ignore-or-rewrite";
+interface Verdict {
+    label: VerdictLabel;
+    headline: string;
+    rationale: string[];
+    action: VerdictAction;
+}
+
+declare const STABILITY_HOOKS_VERSION = 1;
+interface RegionSummary {
+    bbox: BoundingBox;
+    pixelCount: number;
+    percentage: number;
+    changeType: string;
+    confidence: number;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface WaitForSelector {
+    selector: string;
+    timeoutMs?: number;
+}
+type WaitFor = "networkidle" | "fonts" | WaitForSelector;
+interface ManifestEntry {
+    id: string;
+    url: string;
+    viewport: Viewport;
+    auth: null | "required";
+    waitFor: WaitFor[];
+    mask: string[];
+    fullPage?: boolean;
+    baselinePath: string;
+    captureHash: string;
+    createdBy: "agent" | "human";
+    createdAt: string;
+}
+interface Manifest {
+    version: 1;
+    configHash: string;
+    stabilityHooksVersion: number;
+    entries: ManifestEntry[];
+}
+interface DevServerConfig {
+    command: string;
+    port: number;
+    cwd?: string;
+    readyTimeoutMs?: number;
+}
+interface AgentConfig {
+    devServer: DevServerConfig | null;
+    framework?: string;
+    packageManager?: "npm" | "pnpm" | "yarn" | "bun";
+    baseUrl?: string;
+}
+interface CaptureOptions {
+    id: string;
+    url: string;
+    viewport?: Viewport;
+    mask?: string[];
+    waitFor?: WaitFor[];
+    fullPage?: boolean;
+    mode: "baseline" | "actual";
+}
+interface DiscoveredRoute {
+    url: string;
+    source: "next-manifest" | "sitemap" | "crawl";
+    auth?: "required";
+}
+interface CheckReport {
+    createdAt: string;
+    totalEntries: number;
+    passed: number;
+    failed: number;
+    pendingJudgments: number;
+    results: CheckResult[];
+}
+interface CheckResult {
+    id: string;
+    url: string;
+    status: "pass" | "fail" | "missing-baseline" | "stale-baseline" | "needs-judgment";
+    diffCount?: number;
+    diffPercentage?: number;
+    severity?: string;
+    regions?: RegionSummary[];
+    verdict?: Verdict;
+    diffPath?: string;
+    actualPath?: string;
+    baselinePath?: string;
+    message?: string;
+}
+
+interface CaptureResult {
+    id: string;
+    outputPath: string;
+    mode: "baseline" | "actual";
+    bytes: number;
+}
+declare function captureScreenshot(baseUrl: string, opts: CaptureOptions, cwd?: string): Promise<CaptureResult>;
+
+interface BrowsersInstallOptions {
+    check?: boolean;
+}
+interface BrowsersInstallResult {
+    installed: boolean;
+    executablePath: string | null;
+    cliPath: string;
+}
+declare function installBrowsers(opts?: BrowsersInstallOptions): Promise<BrowsersInstallResult>;
+
+interface CaptureRouteInput {
+    id: string;
+    url: string;
+    mask?: string[];
+    viewport?: Viewport;
+    waitFor?: WaitFor[];
+    fullPage?: boolean;
+    mode?: "baseline" | "actual";
+}
+interface RunCapturesOptions {
+    baseUrl: string;
+    routes: CaptureRouteInput[];
+    mode?: "baseline" | "actual";
+    writeManifest?: boolean;
+    cwd?: string;
+}
+interface CaptureRouteResult {
+    id: string;
+    url: string;
+    mode: "baseline" | "actual";
+    ok: boolean;
+    outputPath?: string;
+    bytes?: number;
+    error?: string;
+}
+interface RunCapturesReport {
+    total: number;
+    succeeded: number;
+    failed: number;
+    manifestUpdates: number;
+    results: CaptureRouteResult[];
+}
+declare function runCaptures(opts: RunCapturesOptions): Promise<RunCapturesReport>;
+
+interface JudgeInput {
+    entry: ManifestEntry;
+    baselinePath: string;
+    actualPath: string;
+    diffPath?: string;
+    regions?: RegionSummary[];
+    diffPercentage?: number;
+    severity?: string;
+    heuristicVerdict: Verdict;
+}
+type JudgmentRequestRegion = RegionSummary;
+type JudgeOutput = {
+    kind: "judged";
+    verdict: Verdict;
+    rationale?: string;
+    confidence?: number;
+} | {
+    kind: "deferred";
+    requestPath: string;
+};
+interface Judge {
+    readonly name: string;
+    judge(input: JudgeInput, cwd: string): Promise<JudgeOutput>;
+}
+type JudgeBackend = "none" | "host";
+
+interface ApplyJudgmentsResult {
+    report: CheckReport;
+    applied: string[];
+    missing: string[];
+    invalid: string[];
+}
+declare function applyJudgments(cwd?: string): Promise<ApplyJudgmentsResult>;
+
+interface JudgmentRequest {
+    id: string;
+    url: string;
+    status: CheckResult["status"];
+    diffPercentage?: number;
+    severity?: string;
+    regions?: RegionSummary[];
+    paths: {
+        baseline?: string;
+        actual?: string;
+        diff?: string;
+        locator?: string;
+        tiles?: string;
+    };
+    heuristicVerdict?: Verdict;
+    manifestEntry: {
+        viewport: ManifestEntry["viewport"];
+        mask: ManifestEntry["mask"];
+        waitFor: ManifestEntry["waitFor"];
+        fullPage?: boolean;
+    };
+    signature: string;
+    message?: string;
+    instructions?: string;
+    createdAt: string;
+}
+
+declare function resolveJudge(backend: JudgeBackend): Judge;
+
+interface CheckOptions {
+    baseUrl: string;
+    cwd?: string;
+    threshold?: number;
+    concurrency?: number;
+    emitDiffPng?: boolean;
+    junitPath?: string;
+    judge?: JudgeBackend;
+}
+declare function runCheck(opts: CheckOptions): Promise<CheckReport>;
+
+declare function loadConfig(cwd?: string): Promise<AgentConfig | null>;
+declare function saveConfig(config: AgentConfig, cwd?: string): Promise<void>;
+declare function configHash(config: AgentConfig): string;
+declare function resolveBaseUrl(config: AgentConfig | null, override?: string): string;
+
+interface DiffOptions {
+    threshold?: number;
+    antialiasing?: boolean;
+    emitDiffPng?: boolean;
+}
+interface DiffOutcome {
+    id: string;
+    baselinePath: string;
+    actualPath: string;
+    diffPath?: string;
+    match: boolean;
+    reason?: "pixel-diff" | "layout-diff" | "file-not-exists";
+    diffCount?: number;
+    diffPercentage?: number;
+    interpretation?: InterpretResult;
+}
+declare function diffEntry(id: string, baselinePath: string, actualPath: string, opts?: DiffOptions, cwd?: string): Promise<DiffOutcome>;
+
+interface DiscoverOptions {
+    baseUrl: string;
+    cwd?: string;
+    maxRoutes?: number;
+    skipCrawl?: boolean;
+}
+declare function discover(opts: DiscoverOptions): Promise<DiscoveredRoute[]>;
+
+interface RunOptions {
+    baseUrl: string;
+    cwd?: string;
+    threshold?: number;
+    concurrency?: number;
+    emitDiffPng?: boolean;
+    junitPath?: string;
+    judge?: JudgeBackend;
+}
+declare function runGraph(opts: RunOptions): Promise<CheckReport>;
+
+declare function loadManifest(cwd?: string): Promise<Manifest | null>;
+declare function saveManifest(manifest: Manifest, cwd?: string): Promise<void>;
+
+declare const paths: (cwd?: string) => {
+    root: string;
+    config: string;
+    manifest: string;
+    baselines: string;
+    actual: string;
+    judgments: string;
+    summary: string;
+    gitignore: string;
+    serverLog: string;
+    serverPid: string;
+};
+
+export { type AgentConfig, type ApplyJudgmentsResult, type BrowsersInstallOptions, type BrowsersInstallResult, type CaptureOptions, type CaptureRouteInput, type CaptureRouteResult, type CheckReport, type CheckResult, type DevServerConfig, type DiffOptions, type DiffOutcome, type DiscoveredRoute, type Judge, type JudgeBackend, type JudgeInput, type JudgeOutput, type JudgmentRequest, type JudgmentRequestRegion, type Manifest, type ManifestEntry, type RegionSummary, type RunCapturesOptions, type RunCapturesReport, type RunOptions, STABILITY_HOOKS_VERSION, type Verdict, type VerdictAction, type VerdictLabel, type Viewport, type WaitFor, type WaitForSelector, applyJudgments, captureScreenshot, configHash, diffEntry, discover, installBrowsers, loadConfig, loadManifest, paths, resolveBaseUrl, resolveJudge, runCaptures, runCheck, runGraph, saveConfig, saveManifest };