@cappa/core 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -5,49 +5,37 @@ import { Logger } from "@cappa/logger";
5
5
  import "@blazediff/core-native";
6
6
  //#region src/agent/verdict.d.ts
7
7
  /**
8
- * What a reviewer — heuristic or agent — believes a changed screenshot is.
8
+ * What a judge believes a changed screenshot is, after looking at it.
9
9
  *
10
- * `ambiguous` is only ever produced by the heuristic: it is the signal that
11
- * the change has to be looked at, and an agent's verdict must resolve it into
12
- * one of the other three.
10
+ * Only a judge labels a change. Cappa's diff threshold already absorbs
11
+ * sub-pixel rendering differences, so a screenshot that reaches `changed`
12
+ * differs beyond the tolerance the project configured — and classifying it
13
+ * from diff signals alone (change types, severity, pixel counts) proved to
14
+ * mislabel exactly the changes that matter: a font-size change reads as a
15
+ * harmless shift plus recolour. Every changed screenshot is looked at instead.
13
16
  */
14
- export declare const VERDICT_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely", "ambiguous"];
17
+ export declare const VERDICT_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely"];
15
18
  type VerdictLabel = (typeof VERDICT_LABELS)[number];
16
- /** The labels a judge may hand back — everything but `ambiguous`. */
17
- export declare const JUDGED_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely"];
18
- type JudgedLabel = (typeof JUDGED_LABELS)[number];
19
19
  /** What to do next with a screenshot carrying a label. */
20
20
  type VerdictAction = "investigate" | "approve-if-intended" | "mask-or-approve";
21
21
  export declare const ACTION_BY_LABEL: Record<VerdictLabel, VerdictAction>;
22
22
  type Verdict = {
23
23
  label: VerdictLabel;
24
- /** One line, e.g. `2 regions: 1 addition, 1 color-change @ top-left (1.20%, medium)`. */
24
+ /** One line, e.g. `Submit button label is truncated`. */
25
25
  headline: string;
26
26
  rationale: string[];
27
27
  action: VerdictAction;
28
28
  };
29
29
  export declare const isVerdictLabel: (value: unknown) => value is VerdictLabel;
30
- export declare const isJudgedLabel: (value: unknown) => value is JudgedLabel;
31
30
  /**
32
31
  * Change types are normalised to kebab-case before they are compared.
33
32
  *
34
33
  * `@blazediff/interpret-native` reports `color-change` today but earlier
35
- * releases reported `ColorChange`; normalising keeps the heuristic working
36
- * across a diff-engine upgrade instead of silently degrading every screenshot
37
- * to `ambiguous`.
34
+ * releases reported `ColorChange`; normalising keeps the capture report's
35
+ * labels working across a diff-engine upgrade.
38
36
  */
39
37
  export declare const normalizeChangeType: (changeType: string) => string;
40
- /**
41
- * At or below this many differing pixels, a low-severity change is not
42
- * perceptible.
43
- *
44
- * An absolute count rather than a share of the image: a share depends on how
45
- * much empty canvas surrounds the content, so the same changed glyph would be
46
- * noise in a 1920x1080 capture and a regression in a tight crop of the
47
- * component. The pixels that changed are the same either way.
48
- */
49
- export declare const SUB_PERCEPTUAL_PIXELS = 25;
50
- type VerdictInput = {
38
+ type ChangeInput = {
51
39
  /** Percentage of differing pixels (0-100), from the pixel diff. */
52
40
  percentDifference?: number;
53
41
  numDiffPixels?: number;
@@ -60,21 +48,16 @@ type VerdictInput = {
60
48
  differentSizes?: boolean;
61
49
  };
62
50
  /**
63
- * A one-line description of a change, shaped so that the same kind of change
64
- * on different screenshots produces the same headline — which is what lets an
65
- * agent spot one shared cause (a footer timestamp, a theme toggle) across
66
- * dozens of screenshots without opening any of them.
67
- */
68
- export declare const buildHeadline: (input: VerdictInput) => string;
69
- /**
70
- * Classify a changed screenshot from its diff interpretation alone.
51
+ * A one-line description of where and how much a screenshot changed, shaped
52
+ * so that the same change on different screenshots produces the same text —
53
+ * which is what lets a judge spot one shared cause (a footer timestamp, a
54
+ * theme toggle) across dozens of screenshots and judge them together.
71
55
  *
72
- * Deliberately conservative: only the cases the signals settle are labelled,
73
- * and everything else is `ambiguous` so that it reaches a judge who can look
74
- * at the pixels. A wrong `noise-likely` hides a regression; a wrong
75
- * `ambiguous` costs one look.
56
+ * Deliberately geometry only: no change types, no severity. Those are guesses
57
+ * from pixel signals, and a judge primed with "noise" or "shift" looks less
58
+ * carefully at what is in fact a regression.
76
59
  */
77
- export declare const deriveVerdict: (input: VerdictInput) => Verdict;
60
+ export declare const describeChange: (input: ChangeInput) => string;
78
61
  //#endregion
79
62
  //#region src/consoleEvents.d.ts
80
63
  /**
@@ -1197,20 +1180,23 @@ interface DiffMetadata {
1197
1180
  interpretation?: InterpretResult$1;
1198
1181
  }
1199
1182
  /**
1200
- * The verdict `cappa agent check` reached for a changed screenshot, as the
1201
- * review UI shows it.
1183
+ * A judge's verdict on a changed screenshot, as applied by the last
1184
+ * `cappa agent check` and shown in the review UI.
1202
1185
  */
1203
1186
  interface AgentReview {
1204
1187
  label: VerdictLabel;
1205
1188
  headline: string;
1206
1189
  rationale: string[];
1207
1190
  action: VerdictAction;
1208
- /** `heuristic` from the diff signals; `agent` from a judge's verdict. */
1209
- source: "heuristic" | "agent";
1191
+ /**
1192
+ * Always `agent`: only a judge labels a change. The wire format also
1193
+ * allows `heuristic`, which engines before 0.18 sent.
1194
+ */
1195
+ source: "agent";
1210
1196
  /** 0-1, when the judge gave one. */
1211
1197
  confidence?: number;
1212
- /** A judgment was requested and no verdict had been written yet. */
1213
- pending: boolean;
1198
+ /** Always false: a screenshot awaiting judgment carries no review. */
1199
+ pending: false;
1214
1200
  /** When the check that produced this ran (ISO 8601). */
1215
1201
  reviewedAt: string;
1216
1202
  }
@@ -1225,8 +1211,8 @@ type ChangedScreenshot = {
1225
1211
  */
1226
1212
  diffMeta?: DiffMetadata;
1227
1213
  /**
1228
- * The last `cappa agent check` verdict. Absent when no check has run, or
1229
- * when either image changed since — a verdict about other pixels is not one
1214
+ * The judge's verdict from the last `cappa agent check`. Absent when it is
1215
+ * not judged yet, or when either image changed since — a verdict about other pixels is not one
1230
1216
  * worth showing.
1231
1217
  */
1232
1218
  review?: AgentReview;
@@ -2356,22 +2342,11 @@ export declare class FsScreenshotStore implements ScreenshotStore {
2356
2342
  */
2357
2343
  export declare const AGENT_DIRNAME = ".cappa-agent";
2358
2344
  /** Bumped only if `request.json` or `report.json` change incompatibly. */
2359
- export declare const AGENT_REPORT_VERSION = 1;
2345
+ export declare const AGENT_REPORT_VERSION = 2;
2360
2346
  export declare const agentDir: (outputDir: string) => string;
2361
2347
  export declare const agentReportPath: (outputDir: string) => string;
2362
2348
  //#endregion
2363
2349
  //#region src/agent/review.d.ts
2364
- /**
2365
- * Which changed screenshots get a judgment request.
2366
- *
2367
- * - `ambiguous`: only those the heuristic could not label (default)
2368
- * - `all`: every changed screenshot, for a full second opinion
2369
- * - `none`: heuristic labels only, no new requests
2370
- *
2371
- * Judgments that already exist are kept and applied in every mode.
2372
- */
2373
- type JudgeMode = "ambiguous" | "all" | "none";
2374
- export declare const JUDGE_MODES: readonly JudgeMode[];
2375
2350
  type AgentRegion = {
2376
2351
  /** 1-based, matching the numbers in `locator.png` and rows in `regions.png`. */
2377
2352
  index: number;
@@ -2385,12 +2360,9 @@ type AgentRegion = {
2385
2360
  percentage: number;
2386
2361
  position: string;
2387
2362
  shape: string;
2388
- changeType: string;
2389
- confidence: number;
2390
2363
  };
2364
+ /** A judge's verdict, as applied to a screenshot. */
2391
2365
  type AppliedVerdict = Verdict & {
2392
- /** Whether the label came from the heuristic or from a judge. */
2393
- source: "heuristic" | "agent";
2394
2366
  confidence?: number;
2395
2367
  };
2396
2368
  type JudgmentPaths = {
@@ -2424,14 +2396,16 @@ type AgentReportEntry = {
2424
2396
  height: number;
2425
2397
  };
2426
2398
  };
2427
- severity?: string;
2428
- summary?: string;
2399
+ /**
2400
+ * Where and how much it changed, e.g. `2 regions @ top-left (1.20%)`. The
2401
+ * same change on different screenshots reads the same, so it groups them.
2402
+ */
2403
+ change?: string;
2429
2404
  /** Largest first. */
2430
2405
  regions?: AgentRegion[];
2431
- heuristic?: Verdict;
2432
- /** The judge's verdict when there is a current one, else the heuristic's. */
2406
+ /** The judge's verdict, once one was written about these images. */
2433
2407
  verdict?: AppliedVerdict;
2434
- /** A judgment was requested and no valid verdict has been written yet. */
2408
+ /** A changed screenshot without a valid verdict yet. */
2435
2409
  pending: boolean;
2436
2410
  judgment?: JudgmentPaths;
2437
2411
  /** Why a `verdict.json` that exists was ignored. */
@@ -2442,7 +2416,6 @@ type AgentReport = {
2442
2416
  createdAt: string;
2443
2417
  outputDir: string;
2444
2418
  reportPath: string;
2445
- judge: JudgeMode;
2446
2419
  totals: {
2447
2420
  total: number;
2448
2421
  passed: number;
@@ -2466,7 +2439,7 @@ export declare const judgmentDir: (outputDir: string, name: string) => string;
2466
2439
  export declare const fingerprintImages: (expectedPath: string, actualPath: string) => Promise<string>;
2467
2440
  type ParsedAgentVerdict = {
2468
2441
  ok: true;
2469
- label: JudgedLabel;
2442
+ label: VerdictLabel;
2470
2443
  headline: string;
2471
2444
  rationale: string[];
2472
2445
  confidence?: number;
@@ -2485,7 +2458,6 @@ type RunAgentCheckOptions = {
2485
2458
  outputDir: string;
2486
2459
  /** The project's diff config — its threshold is reused for interpretation. */
2487
2460
  diff?: DiffOptions;
2488
- judge?: JudgeMode;
2489
2461
  /** Regions rendered into `regions.png` per screenshot. Default 8. */
2490
2462
  maxTileRegions?: number;
2491
2463
  /** Screenshots analysed in parallel. Default 4. */
@@ -2499,9 +2471,9 @@ type RunAgentCheckOptions = {
2499
2471
  */
2500
2472
  export declare const clearJudgment: (outputDir: string, name: string) => Promise<void>;
2501
2473
  /**
2502
- * Analyse every non-passing screenshot, write judgment requests for the ones
2503
- * that need a judge, apply any verdicts already written, and persist the
2504
- * full report to `<outputDir>/.cappa-agent/report.json`.
2474
+ * Analyse every non-passing screenshot, write a judgment request for every
2475
+ * changed one, apply any verdicts already written, and persist the full
2476
+ * report to `<outputDir>/.cappa-agent/report.json`.
2505
2477
  */
2506
2478
  export declare const runAgentCheck: (options: RunAgentCheckOptions) => Promise<AgentReport>;
2507
2479
  /** Read the report the last {@link runAgentCheck} wrote, if any. */
@@ -2517,7 +2489,8 @@ type SlimAgentReport = {
2517
2489
  results: Array<{
2518
2490
  name: string;
2519
2491
  category: AgentReportEntry["category"];
2520
- verdict?: Pick<AppliedVerdict, "label" | "headline" | "action" | "source">;
2492
+ change?: string;
2493
+ verdict?: Pick<AppliedVerdict, "label" | "headline" | "action">;
2521
2494
  pending?: true;
2522
2495
  /** Judgment directory, present while a verdict is pending. */
2523
2496
  judgment?: string;
@@ -2531,7 +2504,7 @@ type SlimAgentReport = {
2531
2504
  */
2532
2505
  export declare const toSlimAgentReport: (report: AgentReport) => SlimAgentReport;
2533
2506
  type AgentVerdictInput = {
2534
- label: JudgedLabel;
2507
+ label: VerdictLabel;
2535
2508
  headline: string;
2536
2509
  rationale?: string[];
2537
2510
  confidence?: number;
@@ -2674,5 +2647,5 @@ export declare function findRefusedConnection(error: unknown): RefusedConnection
2674
2647
  */
2675
2648
  export declare function sameServer(a: string, b: string): boolean;
2676
2649
  //#endregion
2677
- export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type JudgeMode, type JudgedLabel, type JudgmentPaths, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type ParsedAgentVerdict, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedWebServerConfig, type RunAgentCheckOptions, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type ServerProcess, type SlimAgentReport, type SpawnServerOptions, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type TileOptions, type TileResult, type UserConfig, type Verdict, type VerdictAction, type VerdictInput, type VerdictLabel, type Viewport, type WaitForUrlOptions, type WaitForUrlResult, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus, type WebServerConfig, type WebServerLog, type WebServerLogLevel, type WebServerPoolOptions };
2650
+ export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeInput, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type JudgmentPaths, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type ParsedAgentVerdict, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedWebServerConfig, type RunAgentCheckOptions, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type ServerProcess, type SlimAgentReport, type SpawnServerOptions, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type TileOptions, type TileResult, type UserConfig, type Verdict, type VerdictAction, type VerdictLabel, type Viewport, type WaitForUrlOptions, type WaitForUrlResult, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus, type WebServerConfig, type WebServerLog, type WebServerLogLevel, type WebServerPoolOptions };
2678
2651
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -5,49 +5,37 @@ import { BoundingBox, ChangeRegion, InterpretResult, InterpretResult as Interpre
5
5
  import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
6
6
  //#region src/agent/verdict.d.ts
7
7
  /**
8
- * What a reviewer — heuristic or agent — believes a changed screenshot is.
8
+ * What a judge believes a changed screenshot is, after looking at it.
9
9
  *
10
- * `ambiguous` is only ever produced by the heuristic: it is the signal that
11
- * the change has to be looked at, and an agent's verdict must resolve it into
12
- * one of the other three.
10
+ * Only a judge labels a change. Cappa's diff threshold already absorbs
11
+ * sub-pixel rendering differences, so a screenshot that reaches `changed`
12
+ * differs beyond the tolerance the project configured — and classifying it
13
+ * from diff signals alone (change types, severity, pixel counts) proved to
14
+ * mislabel exactly the changes that matter: a font-size change reads as a
15
+ * harmless shift plus recolour. Every changed screenshot is looked at instead.
13
16
  */
14
- export declare const VERDICT_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely", "ambiguous"];
17
+ export declare const VERDICT_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely"];
15
18
  type VerdictLabel = (typeof VERDICT_LABELS)[number];
16
- /** The labels a judge may hand back — everything but `ambiguous`. */
17
- export declare const JUDGED_LABELS: readonly ["regression-likely", "intentional-likely", "noise-likely"];
18
- type JudgedLabel = (typeof JUDGED_LABELS)[number];
19
19
  /** What to do next with a screenshot carrying a label. */
20
20
  type VerdictAction = "investigate" | "approve-if-intended" | "mask-or-approve";
21
21
  export declare const ACTION_BY_LABEL: Record<VerdictLabel, VerdictAction>;
22
22
  type Verdict = {
23
23
  label: VerdictLabel;
24
- /** One line, e.g. `2 regions: 1 addition, 1 color-change @ top-left (1.20%, medium)`. */
24
+ /** One line, e.g. `Submit button label is truncated`. */
25
25
  headline: string;
26
26
  rationale: string[];
27
27
  action: VerdictAction;
28
28
  };
29
29
  export declare const isVerdictLabel: (value: unknown) => value is VerdictLabel;
30
- export declare const isJudgedLabel: (value: unknown) => value is JudgedLabel;
31
30
  /**
32
31
  * Change types are normalised to kebab-case before they are compared.
33
32
  *
34
33
  * `@blazediff/interpret-native` reports `color-change` today but earlier
35
- * releases reported `ColorChange`; normalising keeps the heuristic working
36
- * across a diff-engine upgrade instead of silently degrading every screenshot
37
- * to `ambiguous`.
34
+ * releases reported `ColorChange`; normalising keeps the capture report's
35
+ * labels working across a diff-engine upgrade.
38
36
  */
39
37
  export declare const normalizeChangeType: (changeType: string) => string;
40
- /**
41
- * At or below this many differing pixels, a low-severity change is not
42
- * perceptible.
43
- *
44
- * An absolute count rather than a share of the image: a share depends on how
45
- * much empty canvas surrounds the content, so the same changed glyph would be
46
- * noise in a 1920x1080 capture and a regression in a tight crop of the
47
- * component. The pixels that changed are the same either way.
48
- */
49
- export declare const SUB_PERCEPTUAL_PIXELS = 25;
50
- type VerdictInput = {
38
+ type ChangeInput = {
51
39
  /** Percentage of differing pixels (0-100), from the pixel diff. */
52
40
  percentDifference?: number;
53
41
  numDiffPixels?: number;
@@ -60,21 +48,16 @@ type VerdictInput = {
60
48
  differentSizes?: boolean;
61
49
  };
62
50
  /**
63
- * A one-line description of a change, shaped so that the same kind of change
64
- * on different screenshots produces the same headline — which is what lets an
65
- * agent spot one shared cause (a footer timestamp, a theme toggle) across
66
- * dozens of screenshots without opening any of them.
67
- */
68
- export declare const buildHeadline: (input: VerdictInput) => string;
69
- /**
70
- * Classify a changed screenshot from its diff interpretation alone.
51
+ * A one-line description of where and how much a screenshot changed, shaped
52
+ * so that the same change on different screenshots produces the same text —
53
+ * which is what lets a judge spot one shared cause (a footer timestamp, a
54
+ * theme toggle) across dozens of screenshots and judge them together.
71
55
  *
72
- * Deliberately conservative: only the cases the signals settle are labelled,
73
- * and everything else is `ambiguous` so that it reaches a judge who can look
74
- * at the pixels. A wrong `noise-likely` hides a regression; a wrong
75
- * `ambiguous` costs one look.
56
+ * Deliberately geometry only: no change types, no severity. Those are guesses
57
+ * from pixel signals, and a judge primed with "noise" or "shift" looks less
58
+ * carefully at what is in fact a regression.
76
59
  */
77
- export declare const deriveVerdict: (input: VerdictInput) => Verdict;
60
+ export declare const describeChange: (input: ChangeInput) => string;
78
61
  //#endregion
79
62
  //#region src/consoleEvents.d.ts
80
63
  /**
@@ -1197,20 +1180,23 @@ interface DiffMetadata {
1197
1180
  interpretation?: InterpretResult$1;
1198
1181
  }
1199
1182
  /**
1200
- * The verdict `cappa agent check` reached for a changed screenshot, as the
1201
- * review UI shows it.
1183
+ * A judge's verdict on a changed screenshot, as applied by the last
1184
+ * `cappa agent check` and shown in the review UI.
1202
1185
  */
1203
1186
  interface AgentReview {
1204
1187
  label: VerdictLabel;
1205
1188
  headline: string;
1206
1189
  rationale: string[];
1207
1190
  action: VerdictAction;
1208
- /** `heuristic` from the diff signals; `agent` from a judge's verdict. */
1209
- source: "heuristic" | "agent";
1191
+ /**
1192
+ * Always `agent`: only a judge labels a change. The wire format also
1193
+ * allows `heuristic`, which engines before 0.18 sent.
1194
+ */
1195
+ source: "agent";
1210
1196
  /** 0-1, when the judge gave one. */
1211
1197
  confidence?: number;
1212
- /** A judgment was requested and no verdict had been written yet. */
1213
- pending: boolean;
1198
+ /** Always false: a screenshot awaiting judgment carries no review. */
1199
+ pending: false;
1214
1200
  /** When the check that produced this ran (ISO 8601). */
1215
1201
  reviewedAt: string;
1216
1202
  }
@@ -1225,8 +1211,8 @@ type ChangedScreenshot = {
1225
1211
  */
1226
1212
  diffMeta?: DiffMetadata;
1227
1213
  /**
1228
- * The last `cappa agent check` verdict. Absent when no check has run, or
1229
- * when either image changed since — a verdict about other pixels is not one
1214
+ * The judge's verdict from the last `cappa agent check`. Absent when it is
1215
+ * not judged yet, or when either image changed since — a verdict about other pixels is not one
1230
1216
  * worth showing.
1231
1217
  */
1232
1218
  review?: AgentReview;
@@ -2356,22 +2342,11 @@ export declare class FsScreenshotStore implements ScreenshotStore {
2356
2342
  */
2357
2343
  export declare const AGENT_DIRNAME = ".cappa-agent";
2358
2344
  /** Bumped only if `request.json` or `report.json` change incompatibly. */
2359
- export declare const AGENT_REPORT_VERSION = 1;
2345
+ export declare const AGENT_REPORT_VERSION = 2;
2360
2346
  export declare const agentDir: (outputDir: string) => string;
2361
2347
  export declare const agentReportPath: (outputDir: string) => string;
2362
2348
  //#endregion
2363
2349
  //#region src/agent/review.d.ts
2364
- /**
2365
- * Which changed screenshots get a judgment request.
2366
- *
2367
- * - `ambiguous`: only those the heuristic could not label (default)
2368
- * - `all`: every changed screenshot, for a full second opinion
2369
- * - `none`: heuristic labels only, no new requests
2370
- *
2371
- * Judgments that already exist are kept and applied in every mode.
2372
- */
2373
- type JudgeMode = "ambiguous" | "all" | "none";
2374
- export declare const JUDGE_MODES: readonly JudgeMode[];
2375
2350
  type AgentRegion = {
2376
2351
  /** 1-based, matching the numbers in `locator.png` and rows in `regions.png`. */
2377
2352
  index: number;
@@ -2385,12 +2360,9 @@ type AgentRegion = {
2385
2360
  percentage: number;
2386
2361
  position: string;
2387
2362
  shape: string;
2388
- changeType: string;
2389
- confidence: number;
2390
2363
  };
2364
+ /** A judge's verdict, as applied to a screenshot. */
2391
2365
  type AppliedVerdict = Verdict & {
2392
- /** Whether the label came from the heuristic or from a judge. */
2393
- source: "heuristic" | "agent";
2394
2366
  confidence?: number;
2395
2367
  };
2396
2368
  type JudgmentPaths = {
@@ -2424,14 +2396,16 @@ type AgentReportEntry = {
2424
2396
  height: number;
2425
2397
  };
2426
2398
  };
2427
- severity?: string;
2428
- summary?: string;
2399
+ /**
2400
+ * Where and how much it changed, e.g. `2 regions @ top-left (1.20%)`. The
2401
+ * same change on different screenshots reads the same, so it groups them.
2402
+ */
2403
+ change?: string;
2429
2404
  /** Largest first. */
2430
2405
  regions?: AgentRegion[];
2431
- heuristic?: Verdict;
2432
- /** The judge's verdict when there is a current one, else the heuristic's. */
2406
+ /** The judge's verdict, once one was written about these images. */
2433
2407
  verdict?: AppliedVerdict;
2434
- /** A judgment was requested and no valid verdict has been written yet. */
2408
+ /** A changed screenshot without a valid verdict yet. */
2435
2409
  pending: boolean;
2436
2410
  judgment?: JudgmentPaths;
2437
2411
  /** Why a `verdict.json` that exists was ignored. */
@@ -2442,7 +2416,6 @@ type AgentReport = {
2442
2416
  createdAt: string;
2443
2417
  outputDir: string;
2444
2418
  reportPath: string;
2445
- judge: JudgeMode;
2446
2419
  totals: {
2447
2420
  total: number;
2448
2421
  passed: number;
@@ -2466,7 +2439,7 @@ export declare const judgmentDir: (outputDir: string, name: string) => string;
2466
2439
  export declare const fingerprintImages: (expectedPath: string, actualPath: string) => Promise<string>;
2467
2440
  type ParsedAgentVerdict = {
2468
2441
  ok: true;
2469
- label: JudgedLabel;
2442
+ label: VerdictLabel;
2470
2443
  headline: string;
2471
2444
  rationale: string[];
2472
2445
  confidence?: number;
@@ -2485,7 +2458,6 @@ type RunAgentCheckOptions = {
2485
2458
  outputDir: string;
2486
2459
  /** The project's diff config — its threshold is reused for interpretation. */
2487
2460
  diff?: DiffOptions;
2488
- judge?: JudgeMode;
2489
2461
  /** Regions rendered into `regions.png` per screenshot. Default 8. */
2490
2462
  maxTileRegions?: number;
2491
2463
  /** Screenshots analysed in parallel. Default 4. */
@@ -2499,9 +2471,9 @@ type RunAgentCheckOptions = {
2499
2471
  */
2500
2472
  export declare const clearJudgment: (outputDir: string, name: string) => Promise<void>;
2501
2473
  /**
2502
- * Analyse every non-passing screenshot, write judgment requests for the ones
2503
- * that need a judge, apply any verdicts already written, and persist the
2504
- * full report to `<outputDir>/.cappa-agent/report.json`.
2474
+ * Analyse every non-passing screenshot, write a judgment request for every
2475
+ * changed one, apply any verdicts already written, and persist the full
2476
+ * report to `<outputDir>/.cappa-agent/report.json`.
2505
2477
  */
2506
2478
  export declare const runAgentCheck: (options: RunAgentCheckOptions) => Promise<AgentReport>;
2507
2479
  /** Read the report the last {@link runAgentCheck} wrote, if any. */
@@ -2517,7 +2489,8 @@ type SlimAgentReport = {
2517
2489
  results: Array<{
2518
2490
  name: string;
2519
2491
  category: AgentReportEntry["category"];
2520
- verdict?: Pick<AppliedVerdict, "label" | "headline" | "action" | "source">;
2492
+ change?: string;
2493
+ verdict?: Pick<AppliedVerdict, "label" | "headline" | "action">;
2521
2494
  pending?: true;
2522
2495
  /** Judgment directory, present while a verdict is pending. */
2523
2496
  judgment?: string;
@@ -2531,7 +2504,7 @@ type SlimAgentReport = {
2531
2504
  */
2532
2505
  export declare const toSlimAgentReport: (report: AgentReport) => SlimAgentReport;
2533
2506
  type AgentVerdictInput = {
2534
- label: JudgedLabel;
2507
+ label: VerdictLabel;
2535
2508
  headline: string;
2536
2509
  rationale?: string[];
2537
2510
  confidence?: number;
@@ -2674,5 +2647,5 @@ export declare function findRefusedConnection(error: unknown): RefusedConnection
2674
2647
  */
2675
2648
  export declare function sameServer(a: string, b: string): boolean;
2676
2649
  //#endregion
2677
- export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type JudgeMode, type JudgedLabel, type JudgmentPaths, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type ParsedAgentVerdict, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedWebServerConfig, type RunAgentCheckOptions, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type ServerProcess, type SlimAgentReport, type SpawnServerOptions, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type TileOptions, type TileResult, type UserConfig, type Verdict, type VerdictAction, type VerdictInput, type VerdictLabel, type Viewport, type WaitForUrlOptions, type WaitForUrlResult, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus, type WebServerConfig, type WebServerLog, type WebServerLogLevel, type WebServerPoolOptions };
2650
+ export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeInput, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type JudgmentPaths, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type ParsedAgentVerdict, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedWebServerConfig, type RunAgentCheckOptions, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type ServerProcess, type SlimAgentReport, type SpawnServerOptions, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type TileOptions, type TileResult, type UserConfig, type Verdict, type VerdictAction, type VerdictLabel, type Viewport, type WaitForUrlOptions, type WaitForUrlResult, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus, type WebServerConfig, type WebServerLog, type WebServerLogLevel, type WebServerPoolOptions };
2678
2651
  //# sourceMappingURL=index.d.mts.map