@cappa/core 0.18.0 → 0.20.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
@@ -1,3 +1,4 @@
1
+ import { BrowserConfig, BrowserInstance, BrowserName, BrowserProvider, ContainerOptions, DEFAULT_CONTAINER_IMAGE, PlaywrightProviderOptions, ResolvedBrowserConfig, ResolvedContainerOptions, playwright, resolveBrowserConfig, resolveContainerOptions } from "./playwright.cjs";
1
2
  import { BoundingBox, ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
2
3
  import "@blazediff/gmsd";
3
4
  import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
@@ -180,6 +181,110 @@ export declare function compareImages(image1: string | Buffer, image2: string |
180
181
  */
181
182
  export declare function imagesMatch(image1: string | Buffer, image2: string | Buffer, options?: DiffConfig): Promise<boolean>;
182
183
  //#endregion
184
+ //#region src/container.d.ts
185
+ /**
186
+ * Runs the official Playwright image for an exact `playwright-core` version
187
+ * through a container CLI (docker, podman, nerdctl, …) and hands back the
188
+ * `run-server` endpoint.
189
+ *
190
+ * Only subcommands all of those CLIs share are used: `version`, `image
191
+ * inspect`, `pull`, `inspect`, `run`, `port`, `logs`, `ps` and `rm`.
192
+ */
193
+ /** Label on every container cappa starts; `removePlaywrightContainers` finds them by it. */
194
+ export declare const CONTAINER_LABEL = "dev.cappa.playwright";
195
+ type ExecResult = {
196
+ stdout: string;
197
+ stderr: string;
198
+ };
199
+ type Exec = (file: string, args: string[]) => Promise<ExecResult>;
200
+ type PlaywrightContainer = {
201
+ /** `ws://127.0.0.1:<port>/` — pass to `browserType.connect()`. */
202
+ wsEndpoint: string;
203
+ /** Container name, `cappa-playwright-v<version>-<hash>`. */
204
+ name: string;
205
+ /** The image with `{version}` filled in. */
206
+ image: string;
207
+ /** `true` when an already running container was picked up. */
208
+ reused: boolean;
209
+ /** Remove the container. */
210
+ stop(): Promise<void>;
211
+ };
212
+ type EnsureContainerOptions = Omit<ResolvedContainerOptions, "keepAlive"> & {
213
+ /** Exact `playwright-core` version, e.g. `1.63.0`. */
214
+ version: string;
215
+ /**
216
+ * The host's `playwright-core` directory (symlinks resolved). Mounted
217
+ * read-only and run as the server, so the container needs no npm access and
218
+ * runs exactly the client's version — the image only supplies OS and
219
+ * browsers.
220
+ */
221
+ packageDir: string;
222
+ log?: (message: string) => void;
223
+ /** Injection points for tests. */
224
+ exec?: Exec;
225
+ probe?: (url: string) => Promise<boolean>;
226
+ sleep?: (ms: number) => Promise<void>;
227
+ now?: () => number;
228
+ };
229
+ /**
230
+ * Start — or reuse — the Playwright server container for `version` and wait
231
+ * until it accepts connections.
232
+ */
233
+ export declare function ensurePlaywrightContainer(options: EnsureContainerOptions): Promise<PlaywrightContainer>;
234
+ /**
235
+ * Remove every container cappa started, whatever its version. Returns their
236
+ * names.
237
+ */
238
+ export declare function removePlaywrightContainers(options: {
239
+ cli: string;
240
+ exec?: Exec;
241
+ }): Promise<string[]>;
242
+ //#endregion
243
+ //#region src/features/png/pixelRatio.d.ts
244
+ /**
245
+ * A screenshot's pixel ratio — image pixels per CSS pixel — stored in the PNG
246
+ * itself.
247
+ *
248
+ * Kept in the file rather than beside it because `approve` is a plain copy:
249
+ * the baseline carries the ratio it was captured at through approve, git and
250
+ * CI artifacts with no bookkeeping.
251
+ *
252
+ * Two chunks, both before the image data:
253
+ * - a `tEXt` chunk keyed `cappa:pixelRatio` — the source of truth. Only cappa
254
+ * writes it, so an image another tool stamped with a DPI is never misread.
255
+ * - a standard `pHYs` chunk, which image viewers read as DPI, so a 2×
256
+ * screenshot opens at its CSS size in tools that honour it.
257
+ *
258
+ * Only written for ratios other than 1. A PNG without the key is 1×, which is
259
+ * what every screenshot taken with `scale: "css"` is — so those stay
260
+ * byte-for-byte what they were, and `fastBufferCheck` keeps matching them.
261
+ */
262
+ export declare const PIXEL_RATIO_KEY = "cappa:pixelRatio";
263
+ /**
264
+ * Return `buffer` stamped with `ratio`, replacing any ratio it carried.
265
+ *
266
+ * Ratio 1 removes cappa's chunks instead (see above); a `pHYs` some other tool
267
+ * wrote is left alone unless cappa is writing its own. Anything that is not a
268
+ * PNG comes back untouched. No pixel data is re-encoded.
269
+ */
270
+ export declare function withPixelRatio(buffer: Buffer, ratio: number): Buffer;
271
+ /**
272
+ * The pixel ratio a screenshot was captured at: 1 when the PNG carries no
273
+ * ratio, and also when the file cannot be read — a missing ratio must never
274
+ * break listing or comparing screenshots.
275
+ */
276
+ export declare function readPixelRatio(source: string | Buffer): Promise<number>;
277
+ /** The ratios of a baseline and the screenshot compared against it. */
278
+ type PixelRatioPair = {
279
+ expected: number;
280
+ actual: number;
281
+ };
282
+ /**
283
+ * Why a screenshot cannot match its baseline when the two were captured at
284
+ * different pixel ratios — `screenshot.scale` or `deviceScaleFactor` changed.
285
+ */
286
+ export declare function describePixelRatioMismatch(expected: number, actual: number): string;
287
+ //#endregion
183
288
  //#region src/filesystem.d.ts
184
289
  /**
185
290
  * Map a diff image path to its sidecar metadata path (`.png` -> `.json`).
@@ -598,8 +703,16 @@ type ScreenshotLogSink = (level: RunLogLevel, message: string, ...args: unknown[
598
703
  */
599
704
  type ScreenshotCaptureSink = (page: Page, filename: string) => void;
600
705
  declare class ScreenshotTool {
601
- browserType: "chromium" | "firefox" | "webkit";
706
+ browserType: BrowserName;
602
707
  headless: boolean;
708
+ /** Browser provider, headless mode and instance — see `UserConfig.browser`. */
709
+ browserConfig: ResolvedBrowserConfig;
710
+ /**
711
+ * Set when the browser goes away underneath the tool — a remote browser
712
+ * server restarting, or a local browser crashing. `WarmBrowser` checks it so
713
+ * it starts a fresh browser instead of handing out a dead one.
714
+ */
715
+ disconnected: boolean;
603
716
  viewport: {
604
717
  width: number;
605
718
  height: number;
@@ -607,6 +720,8 @@ declare class ScreenshotTool {
607
720
  fullPage: boolean;
608
721
  /** Default content crop; a screenshot's own `crop` overrides it. */
609
722
  crop: CropSetting;
723
+ /** Default `scale`; a screenshot's own `scale` overrides it. */
724
+ scale: ScreenshotScale;
610
725
  outputDir: string;
611
726
  browser: Browser | null;
612
727
  context: BrowserContext | null;
@@ -627,13 +742,20 @@ declare class ScreenshotTool {
627
742
  filesystem: ScreenshotFileSystem;
628
743
  logConsoleEvents: LogConsoleEvents;
629
744
  connectionTimeout: number;
745
+ /** The container `init()` started or reused, when `container` is on. */
746
+ container: PlaywrightContainer | null;
630
747
  private defaultUserAgent;
631
748
  /** The real logger, kept so `setLogSink(null)` restores the same instance. */
632
749
  private readonly baseLogger;
633
750
  /** Set while a `CaptureRunner` owns this tool — see `setCaptureSink`. */
634
751
  private captureSink;
635
752
  constructor(options: {
636
- browserType?: "chromium" | "firefox" | "webkit";
753
+ /**
754
+ * Provider, headless mode and instance. When given, `browserType` and
755
+ * `headless` are ignored — they are derived from it.
756
+ */
757
+ browser?: BrowserConfig;
758
+ browserType?: BrowserName;
637
759
  headless?: boolean;
638
760
  viewport?: {
639
761
  width: number;
@@ -641,6 +763,7 @@ declare class ScreenshotTool {
641
763
  };
642
764
  fullPage?: boolean;
643
765
  crop?: CropSetting;
766
+ scale?: ScreenshotScale;
644
767
  outputDir?: string;
645
768
  diff?: DiffOptions;
646
769
  retries?: number;
@@ -681,6 +804,10 @@ declare class ScreenshotTool {
681
804
  init(): Promise<void>;
682
805
  /**
683
806
  * Create the pool of browser contexts and pages.
807
+ *
808
+ * `contextOptions` from the provider merge over cappa's defaults; the
809
+ * viewport and the `CappaStorybook` user-agent suffix always win, because
810
+ * plugins and `isCappa()` rely on them.
684
811
  */
685
812
  private createContexts;
686
813
  /**
@@ -724,6 +851,14 @@ declare class ScreenshotTool {
724
851
  * the same render the screenshot does — and every retry measures afresh.
725
852
  */
726
853
  private shoot;
854
+ /**
855
+ * Image pixels per CSS pixel for a screenshot taken with `options`: the
856
+ * context's `deviceScaleFactor` with `scale: "device"`, else 1.
857
+ *
858
+ * Stamped into every PNG (see `features/png/pixelRatio.ts`) so a baseline
859
+ * remembers the ratio it was captured at.
860
+ */
861
+ pixelRatioFor(options: Pick<ScreenshotSettings, "scale">): number;
727
862
  /**
728
863
  * Sets the viewport size and executes the action, ensuring the original viewport is restored
729
864
  * even if the action throws an error.
@@ -740,11 +875,17 @@ declare class ScreenshotTool {
740
875
  screenshotPath: string;
741
876
  comparisonResult: CompareResult$1 | CompareResult;
742
877
  diffImagePath?: string;
878
+ /** Set when the baseline was captured at another pixel ratio. */
879
+ pixelRatio?: PixelRatioPair;
743
880
  }>;
744
881
  retryScreenshot(page: Page, referenceImage: string | Buffer, options: ScreenshotSettings, diffOverride?: DiffOptions): Promise<{
745
882
  screenshotPath: Buffer<ArrayBufferLike>;
746
883
  comparisonResult: CompareResult | CompareResult$1;
747
884
  passed: boolean;
885
+ pixelRatio?: {
886
+ expected: number;
887
+ actual: number;
888
+ } | undefined;
748
889
  } | {
749
890
  screenshotPath: null;
750
891
  comparisonResult: null;
@@ -1095,7 +1236,38 @@ type UserConfig = {
1095
1236
  * @default false
1096
1237
  */
1097
1238
  crop?: CropSetting;
1239
+ /**
1240
+ * How a screenshot's pixels map to the page's — Playwright's `scale`.
1241
+ *
1242
+ * - `"css"`: one image pixel per CSS pixel, whatever the context's
1243
+ * `deviceScaleFactor`. A 100×40 button is a 100×40 PNG.
1244
+ * - `"device"`: one image pixel per device pixel, so the PNG is
1245
+ * `deviceScaleFactor` times larger — sharp captures of small components.
1246
+ * Set `deviceScaleFactor` through `browser.provider`'s `contextOptions`.
1247
+ *
1248
+ * Changing it changes the size of every screenshot, so existing baselines
1249
+ * need re-approving. Pixel-count thresholds (`maxDiffPixels`) grow with
1250
+ * the square of the scale factor; `maxDiffPercentage` does not.
1251
+ * Plugins and per-screenshot options can override it.
1252
+ * @default "css"
1253
+ */
1254
+ scale?: ScreenshotScale;
1098
1255
  };
1256
+ /**
1257
+ * The browser screenshots are taken in. Shaped like Vitest browser mode's
1258
+ * `browser` block.
1259
+ *
1260
+ * @example
1261
+ * import { playwright } from "@cappa/core/playwright";
1262
+ *
1263
+ * browser: {
1264
+ * provider: playwright({
1265
+ * // unset → cappa launches a local browser
1266
+ * connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
1267
+ * }),
1268
+ * }
1269
+ */
1270
+ browser?: BrowserConfig;
1099
1271
  /**
1100
1272
  * Configuration for the review UI.
1101
1273
  */
@@ -1129,6 +1301,8 @@ type Viewport = {
1129
1301
  width: number;
1130
1302
  height: number;
1131
1303
  };
1304
+ /** See `UserConfig.screenshot.scale`. */
1305
+ type ScreenshotScale = "css" | "device";
1132
1306
  type ScreenshotSettings = {
1133
1307
  fullPage?: boolean;
1134
1308
  /**
@@ -1141,6 +1315,11 @@ type ScreenshotSettings = {
1141
1315
  mask?: Locator[];
1142
1316
  omitBackground?: boolean;
1143
1317
  viewport?: Viewport;
1318
+ /**
1319
+ * `"css"` or `"device"` pixels — see `UserConfig.screenshot.scale`.
1320
+ * Overrides the global setting for this screenshot.
1321
+ */
1322
+ scale?: ScreenshotScale;
1144
1323
  };
1145
1324
  type ScreenshotVariant = {
1146
1325
  id: string;
@@ -1241,6 +1420,14 @@ type Screenshot = {
1241
1420
  taskId?: string;
1242
1421
  /** Plugin that owns `taskId`. Absent whenever `taskId` is. */
1243
1422
  plugin?: string;
1423
+ /**
1424
+ * Image pixels per CSS pixel of the actual / expected PNG, as stamped at
1425
+ * capture (`screenshot.scale: "device"` → the `deviceScaleFactor`). Absent
1426
+ * means 1. Divide an image's size by it to show it at its CSS size; two
1427
+ * different ratios mean the baseline predates a scale change.
1428
+ */
1429
+ actualPixelRatio?: number;
1430
+ expectedPixelRatio?: number;
1244
1431
  } & (NewScreenshot | DeletedScreenshot | ChangedScreenshot | PassedScreenshot);
1245
1432
  type FailedScreenshot = Screenshot & {
1246
1433
  /**
@@ -1964,8 +2151,11 @@ type LocalEngineOptions = {
1964
2151
  logConsoleEvents?: LogConsoleEvents;
1965
2152
  fullPage?: boolean;
1966
2153
  crop?: CropSetting;
2154
+ scale?: ScreenshotScale;
1967
2155
  viewport?: Viewport;
1968
2156
  connectionTimeout?: number;
2157
+ /** Provider, headless mode and instance — see `UserConfig.browser`. */
2158
+ browser?: BrowserConfig;
1969
2159
  /**
1970
2160
  * How long the browser stays warm between runs.
1971
2161
  * @default 300_000 (5 minutes)
@@ -2647,5 +2837,5 @@ export declare function findRefusedConnection(error: unknown): RefusedConnection
2647
2837
  */
2648
2838
  export declare function sameServer(a: string, b: string): boolean;
2649
2839
  //#endregion
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 };
2840
+ export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type BrowserConfig, type BrowserInstance, type BrowserName, type BrowserProvider, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeInput, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContainerOptions, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, DEFAULT_CONTAINER_IMAGE, 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 PixelRatioPair, type PlaywrightContainer, type PlaywrightProviderOptions, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedBrowserConfig, type ResolvedContainerOptions, 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 ScreenshotScale, 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, playwright, resolveBrowserConfig, resolveContainerOptions };
2651
2841
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { BrowserConfig, BrowserInstance, BrowserName, BrowserProvider, ContainerOptions, DEFAULT_CONTAINER_IMAGE, PlaywrightProviderOptions, ResolvedBrowserConfig, ResolvedContainerOptions, playwright, resolveBrowserConfig, resolveContainerOptions } from "./playwright.mjs";
1
2
  import "@blazediff/gmsd";
2
3
  import { Logger } from "@cappa/logger";
3
4
  import "@blazediff/core-native";
@@ -180,6 +181,110 @@ export declare function compareImages(image1: string | Buffer, image2: string |
180
181
  */
181
182
  export declare function imagesMatch(image1: string | Buffer, image2: string | Buffer, options?: DiffConfig): Promise<boolean>;
182
183
  //#endregion
184
+ //#region src/container.d.ts
185
+ /**
186
+ * Runs the official Playwright image for an exact `playwright-core` version
187
+ * through a container CLI (docker, podman, nerdctl, …) and hands back the
188
+ * `run-server` endpoint.
189
+ *
190
+ * Only subcommands all of those CLIs share are used: `version`, `image
191
+ * inspect`, `pull`, `inspect`, `run`, `port`, `logs`, `ps` and `rm`.
192
+ */
193
+ /** Label on every container cappa starts; `removePlaywrightContainers` finds them by it. */
194
+ export declare const CONTAINER_LABEL = "dev.cappa.playwright";
195
+ type ExecResult = {
196
+ stdout: string;
197
+ stderr: string;
198
+ };
199
+ type Exec = (file: string, args: string[]) => Promise<ExecResult>;
200
+ type PlaywrightContainer = {
201
+ /** `ws://127.0.0.1:<port>/` — pass to `browserType.connect()`. */
202
+ wsEndpoint: string;
203
+ /** Container name, `cappa-playwright-v<version>-<hash>`. */
204
+ name: string;
205
+ /** The image with `{version}` filled in. */
206
+ image: string;
207
+ /** `true` when an already running container was picked up. */
208
+ reused: boolean;
209
+ /** Remove the container. */
210
+ stop(): Promise<void>;
211
+ };
212
+ type EnsureContainerOptions = Omit<ResolvedContainerOptions, "keepAlive"> & {
213
+ /** Exact `playwright-core` version, e.g. `1.63.0`. */
214
+ version: string;
215
+ /**
216
+ * The host's `playwright-core` directory (symlinks resolved). Mounted
217
+ * read-only and run as the server, so the container needs no npm access and
218
+ * runs exactly the client's version — the image only supplies OS and
219
+ * browsers.
220
+ */
221
+ packageDir: string;
222
+ log?: (message: string) => void;
223
+ /** Injection points for tests. */
224
+ exec?: Exec;
225
+ probe?: (url: string) => Promise<boolean>;
226
+ sleep?: (ms: number) => Promise<void>;
227
+ now?: () => number;
228
+ };
229
+ /**
230
+ * Start — or reuse — the Playwright server container for `version` and wait
231
+ * until it accepts connections.
232
+ */
233
+ export declare function ensurePlaywrightContainer(options: EnsureContainerOptions): Promise<PlaywrightContainer>;
234
+ /**
235
+ * Remove every container cappa started, whatever its version. Returns their
236
+ * names.
237
+ */
238
+ export declare function removePlaywrightContainers(options: {
239
+ cli: string;
240
+ exec?: Exec;
241
+ }): Promise<string[]>;
242
+ //#endregion
243
+ //#region src/features/png/pixelRatio.d.ts
244
+ /**
245
+ * A screenshot's pixel ratio — image pixels per CSS pixel — stored in the PNG
246
+ * itself.
247
+ *
248
+ * Kept in the file rather than beside it because `approve` is a plain copy:
249
+ * the baseline carries the ratio it was captured at through approve, git and
250
+ * CI artifacts with no bookkeeping.
251
+ *
252
+ * Two chunks, both before the image data:
253
+ * - a `tEXt` chunk keyed `cappa:pixelRatio` — the source of truth. Only cappa
254
+ * writes it, so an image another tool stamped with a DPI is never misread.
255
+ * - a standard `pHYs` chunk, which image viewers read as DPI, so a 2×
256
+ * screenshot opens at its CSS size in tools that honour it.
257
+ *
258
+ * Only written for ratios other than 1. A PNG without the key is 1×, which is
259
+ * what every screenshot taken with `scale: "css"` is — so those stay
260
+ * byte-for-byte what they were, and `fastBufferCheck` keeps matching them.
261
+ */
262
+ export declare const PIXEL_RATIO_KEY = "cappa:pixelRatio";
263
+ /**
264
+ * Return `buffer` stamped with `ratio`, replacing any ratio it carried.
265
+ *
266
+ * Ratio 1 removes cappa's chunks instead (see above); a `pHYs` some other tool
267
+ * wrote is left alone unless cappa is writing its own. Anything that is not a
268
+ * PNG comes back untouched. No pixel data is re-encoded.
269
+ */
270
+ export declare function withPixelRatio(buffer: Buffer, ratio: number): Buffer;
271
+ /**
272
+ * The pixel ratio a screenshot was captured at: 1 when the PNG carries no
273
+ * ratio, and also when the file cannot be read — a missing ratio must never
274
+ * break listing or comparing screenshots.
275
+ */
276
+ export declare function readPixelRatio(source: string | Buffer): Promise<number>;
277
+ /** The ratios of a baseline and the screenshot compared against it. */
278
+ type PixelRatioPair = {
279
+ expected: number;
280
+ actual: number;
281
+ };
282
+ /**
283
+ * Why a screenshot cannot match its baseline when the two were captured at
284
+ * different pixel ratios — `screenshot.scale` or `deviceScaleFactor` changed.
285
+ */
286
+ export declare function describePixelRatioMismatch(expected: number, actual: number): string;
287
+ //#endregion
183
288
  //#region src/filesystem.d.ts
184
289
  /**
185
290
  * Map a diff image path to its sidecar metadata path (`.png` -> `.json`).
@@ -598,8 +703,16 @@ type ScreenshotLogSink = (level: RunLogLevel, message: string, ...args: unknown[
598
703
  */
599
704
  type ScreenshotCaptureSink = (page: Page, filename: string) => void;
600
705
  declare class ScreenshotTool {
601
- browserType: "chromium" | "firefox" | "webkit";
706
+ browserType: BrowserName;
602
707
  headless: boolean;
708
+ /** Browser provider, headless mode and instance — see `UserConfig.browser`. */
709
+ browserConfig: ResolvedBrowserConfig;
710
+ /**
711
+ * Set when the browser goes away underneath the tool — a remote browser
712
+ * server restarting, or a local browser crashing. `WarmBrowser` checks it so
713
+ * it starts a fresh browser instead of handing out a dead one.
714
+ */
715
+ disconnected: boolean;
603
716
  viewport: {
604
717
  width: number;
605
718
  height: number;
@@ -607,6 +720,8 @@ declare class ScreenshotTool {
607
720
  fullPage: boolean;
608
721
  /** Default content crop; a screenshot's own `crop` overrides it. */
609
722
  crop: CropSetting;
723
+ /** Default `scale`; a screenshot's own `scale` overrides it. */
724
+ scale: ScreenshotScale;
610
725
  outputDir: string;
611
726
  browser: Browser | null;
612
727
  context: BrowserContext | null;
@@ -627,13 +742,20 @@ declare class ScreenshotTool {
627
742
  filesystem: ScreenshotFileSystem;
628
743
  logConsoleEvents: LogConsoleEvents;
629
744
  connectionTimeout: number;
745
+ /** The container `init()` started or reused, when `container` is on. */
746
+ container: PlaywrightContainer | null;
630
747
  private defaultUserAgent;
631
748
  /** The real logger, kept so `setLogSink(null)` restores the same instance. */
632
749
  private readonly baseLogger;
633
750
  /** Set while a `CaptureRunner` owns this tool — see `setCaptureSink`. */
634
751
  private captureSink;
635
752
  constructor(options: {
636
- browserType?: "chromium" | "firefox" | "webkit";
753
+ /**
754
+ * Provider, headless mode and instance. When given, `browserType` and
755
+ * `headless` are ignored — they are derived from it.
756
+ */
757
+ browser?: BrowserConfig;
758
+ browserType?: BrowserName;
637
759
  headless?: boolean;
638
760
  viewport?: {
639
761
  width: number;
@@ -641,6 +763,7 @@ declare class ScreenshotTool {
641
763
  };
642
764
  fullPage?: boolean;
643
765
  crop?: CropSetting;
766
+ scale?: ScreenshotScale;
644
767
  outputDir?: string;
645
768
  diff?: DiffOptions;
646
769
  retries?: number;
@@ -681,6 +804,10 @@ declare class ScreenshotTool {
681
804
  init(): Promise<void>;
682
805
  /**
683
806
  * Create the pool of browser contexts and pages.
807
+ *
808
+ * `contextOptions` from the provider merge over cappa's defaults; the
809
+ * viewport and the `CappaStorybook` user-agent suffix always win, because
810
+ * plugins and `isCappa()` rely on them.
684
811
  */
685
812
  private createContexts;
686
813
  /**
@@ -724,6 +851,14 @@ declare class ScreenshotTool {
724
851
  * the same render the screenshot does — and every retry measures afresh.
725
852
  */
726
853
  private shoot;
854
+ /**
855
+ * Image pixels per CSS pixel for a screenshot taken with `options`: the
856
+ * context's `deviceScaleFactor` with `scale: "device"`, else 1.
857
+ *
858
+ * Stamped into every PNG (see `features/png/pixelRatio.ts`) so a baseline
859
+ * remembers the ratio it was captured at.
860
+ */
861
+ pixelRatioFor(options: Pick<ScreenshotSettings, "scale">): number;
727
862
  /**
728
863
  * Sets the viewport size and executes the action, ensuring the original viewport is restored
729
864
  * even if the action throws an error.
@@ -740,11 +875,17 @@ declare class ScreenshotTool {
740
875
  screenshotPath: string;
741
876
  comparisonResult: CompareResult$1 | CompareResult;
742
877
  diffImagePath?: string;
878
+ /** Set when the baseline was captured at another pixel ratio. */
879
+ pixelRatio?: PixelRatioPair;
743
880
  }>;
744
881
  retryScreenshot(page: Page, referenceImage: string | Buffer, options: ScreenshotSettings, diffOverride?: DiffOptions): Promise<{
745
882
  screenshotPath: Buffer<ArrayBufferLike>;
746
883
  comparisonResult: CompareResult | CompareResult$1;
747
884
  passed: boolean;
885
+ pixelRatio?: {
886
+ expected: number;
887
+ actual: number;
888
+ } | undefined;
748
889
  } | {
749
890
  screenshotPath: null;
750
891
  comparisonResult: null;
@@ -1095,7 +1236,38 @@ type UserConfig = {
1095
1236
  * @default false
1096
1237
  */
1097
1238
  crop?: CropSetting;
1239
+ /**
1240
+ * How a screenshot's pixels map to the page's — Playwright's `scale`.
1241
+ *
1242
+ * - `"css"`: one image pixel per CSS pixel, whatever the context's
1243
+ * `deviceScaleFactor`. A 100×40 button is a 100×40 PNG.
1244
+ * - `"device"`: one image pixel per device pixel, so the PNG is
1245
+ * `deviceScaleFactor` times larger — sharp captures of small components.
1246
+ * Set `deviceScaleFactor` through `browser.provider`'s `contextOptions`.
1247
+ *
1248
+ * Changing it changes the size of every screenshot, so existing baselines
1249
+ * need re-approving. Pixel-count thresholds (`maxDiffPixels`) grow with
1250
+ * the square of the scale factor; `maxDiffPercentage` does not.
1251
+ * Plugins and per-screenshot options can override it.
1252
+ * @default "css"
1253
+ */
1254
+ scale?: ScreenshotScale;
1098
1255
  };
1256
+ /**
1257
+ * The browser screenshots are taken in. Shaped like Vitest browser mode's
1258
+ * `browser` block.
1259
+ *
1260
+ * @example
1261
+ * import { playwright } from "@cappa/core/playwright";
1262
+ *
1263
+ * browser: {
1264
+ * provider: playwright({
1265
+ * // unset → cappa launches a local browser
1266
+ * connectOptions: { wsEndpoint: process.env.CAPPA_BROWSER_WS },
1267
+ * }),
1268
+ * }
1269
+ */
1270
+ browser?: BrowserConfig;
1099
1271
  /**
1100
1272
  * Configuration for the review UI.
1101
1273
  */
@@ -1129,6 +1301,8 @@ type Viewport = {
1129
1301
  width: number;
1130
1302
  height: number;
1131
1303
  };
1304
+ /** See `UserConfig.screenshot.scale`. */
1305
+ type ScreenshotScale = "css" | "device";
1132
1306
  type ScreenshotSettings = {
1133
1307
  fullPage?: boolean;
1134
1308
  /**
@@ -1141,6 +1315,11 @@ type ScreenshotSettings = {
1141
1315
  mask?: Locator[];
1142
1316
  omitBackground?: boolean;
1143
1317
  viewport?: Viewport;
1318
+ /**
1319
+ * `"css"` or `"device"` pixels — see `UserConfig.screenshot.scale`.
1320
+ * Overrides the global setting for this screenshot.
1321
+ */
1322
+ scale?: ScreenshotScale;
1144
1323
  };
1145
1324
  type ScreenshotVariant = {
1146
1325
  id: string;
@@ -1241,6 +1420,14 @@ type Screenshot = {
1241
1420
  taskId?: string;
1242
1421
  /** Plugin that owns `taskId`. Absent whenever `taskId` is. */
1243
1422
  plugin?: string;
1423
+ /**
1424
+ * Image pixels per CSS pixel of the actual / expected PNG, as stamped at
1425
+ * capture (`screenshot.scale: "device"` → the `deviceScaleFactor`). Absent
1426
+ * means 1. Divide an image's size by it to show it at its CSS size; two
1427
+ * different ratios mean the baseline predates a scale change.
1428
+ */
1429
+ actualPixelRatio?: number;
1430
+ expectedPixelRatio?: number;
1244
1431
  } & (NewScreenshot | DeletedScreenshot | ChangedScreenshot | PassedScreenshot);
1245
1432
  type FailedScreenshot = Screenshot & {
1246
1433
  /**
@@ -1964,8 +2151,11 @@ type LocalEngineOptions = {
1964
2151
  logConsoleEvents?: LogConsoleEvents;
1965
2152
  fullPage?: boolean;
1966
2153
  crop?: CropSetting;
2154
+ scale?: ScreenshotScale;
1967
2155
  viewport?: Viewport;
1968
2156
  connectionTimeout?: number;
2157
+ /** Provider, headless mode and instance — see `UserConfig.browser`. */
2158
+ browser?: BrowserConfig;
1969
2159
  /**
1970
2160
  * How long the browser stays warm between runs.
1971
2161
  * @default 300_000 (5 minutes)
@@ -2647,5 +2837,5 @@ export declare function findRefusedConnection(error: unknown): RefusedConnection
2647
2837
  */
2648
2838
  export declare function sameServer(a: string, b: string): boolean;
2649
2839
  //#endregion
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 };
2840
+ export { type AgentRegion, type AgentReport, type AgentReportEntry, type AgentReview, type AgentVerdictInput, type AppliedVerdict, type ApproveResult, type BrowserConfig, type BrowserInstance, type BrowserName, type BrowserProvider, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeInput, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type ContainerOptions, type ContentCropOptions, type CreateFileWatcher, type CropRect, type CropSetting, DEFAULT_CONTAINER_IMAGE, 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 PixelRatioPair, type PlaywrightContainer, type PlaywrightProviderOptions, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type ProcessExit, type RefusedConnection, type ResolvedBrowserConfig, type ResolvedContainerOptions, 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 ScreenshotScale, 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, playwright, resolveBrowserConfig, resolveContainerOptions };
2651
2841
  //# sourceMappingURL=index.d.mts.map