@cappa/core 0.0.2

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/CHANGELOG.md ADDED
@@ -0,0 +1,7 @@
1
+ # @cappa/core
2
+
3
+ ## 0.0.2
4
+
5
+ ### Patch Changes
6
+
7
+ - b3d2806: Init
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "@cappa/core",
3
+ "version": "0.0.2",
4
+ "description": "Core Playwright screenshot functionality for Cappa",
5
+ "author": "tim-richter",
6
+ "license": "MIT",
7
+ "publishConfig": {
8
+ "access": "public"
9
+ },
10
+ "sideEffects": false,
11
+ "main": "./dist/index.js",
12
+ "types": "./dist/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "import": "./dist/index.mjs",
16
+ "require": "./dist/index.js"
17
+ },
18
+ "./package.json": "./package.json"
19
+ },
20
+ "dependencies": {
21
+ "playwright": "^1.54.2"
22
+ },
23
+ "devDependencies": {
24
+ "tsdown": "0.14.1",
25
+ "@types/node": "22.13.10",
26
+ "vitest": "3.2.4",
27
+ "@vitest/ui": "3.2.4",
28
+ "@vitest/coverage-v8": "3.2.4",
29
+ "typescript": "5.7.3"
30
+ },
31
+ "keywords": [
32
+ "screenshot",
33
+ "playwright",
34
+ "core"
35
+ ],
36
+ "module": "./dist/index.mjs",
37
+ "scripts": {
38
+ "test": "echo \"Error: no test specified\" && exit 1",
39
+ "example:basic": "node examples/basic-usage.js",
40
+ "example:batch": "node examples/batch-screenshots.js",
41
+ "example:responsive": "node examples/responsive-screenshots.js",
42
+ "example:element": "node examples/element-screenshots.js",
43
+ "build": "tsdown"
44
+ }
45
+ }
package/src/config.ts ADDED
@@ -0,0 +1,13 @@
1
+ import type { PossiblePromise } from "./utils/types";
2
+ import type { UserConfig } from "./types";
3
+
4
+ /**
5
+ * Type helper to make it easier to use vite.config.ts accepts a direct UserConfig object, or a function that returns it. The function receives a ConfigEnv object.
6
+ */
7
+ export function defineConfig(
8
+ options:
9
+ | PossiblePromise<UserConfig | Array<UserConfig>>
10
+ | (() => PossiblePromise<UserConfig | Array<UserConfig>>)
11
+ ): typeof options {
12
+ return options;
13
+ }
package/src/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ import ScreenshotTool from "./screenshot";
2
+ import type { PluginFunction, Plugin, PluginDef } from "./plugin";
3
+ import { defineConfig } from "./config";
4
+ import type { Exposed, ScreenshotOptions, UserConfig } from "./types";
5
+
6
+ export {
7
+ ScreenshotTool,
8
+ defineConfig,
9
+ type PluginFunction,
10
+ type Plugin,
11
+ type PluginDef,
12
+ type UserConfig,
13
+ type ScreenshotOptions,
14
+ type Exposed,
15
+ };
package/src/plugin.ts ADDED
@@ -0,0 +1,25 @@
1
+ import ScreenshotTool from "./screenshot";
2
+
3
+ /**
4
+ * Plugin function type definition
5
+ */
6
+ export type PluginFunction = (
7
+ screenshotTool: ScreenshotTool,
8
+ options?: any
9
+ ) => Promise<any[]>;
10
+
11
+ /**
12
+ * Plugin definition interface
13
+ */
14
+ export type PluginDef = {
15
+ name: string;
16
+ description: string;
17
+ version: string;
18
+ execute: PluginFunction;
19
+ validateOptions?: (options: any) => boolean;
20
+ };
21
+
22
+ /**
23
+ * Plugin function type definition
24
+ */
25
+ export type Plugin<Config = any> = (config?: Config) => PluginDef;
@@ -0,0 +1,298 @@
1
+ import {
2
+ type Browser,
3
+ type BrowserContext,
4
+ chromium,
5
+ firefox,
6
+ type Page,
7
+ type PageScreenshotOptions,
8
+ webkit,
9
+ } from "playwright";
10
+ import path from "node:path";
11
+ import fs from "node:fs";
12
+
13
+ class ScreenshotTool {
14
+ browserType: string;
15
+ headless: boolean;
16
+ viewport: { width: number; height: number };
17
+ outputDir: string;
18
+ quality: number;
19
+ fullPage: boolean;
20
+ browser: Browser | null = null;
21
+ context: BrowserContext | null = null;
22
+ constructor(options: {
23
+ browserType?: string;
24
+ headless?: boolean;
25
+ viewport?: { width: number; height: number };
26
+ outputDir?: string;
27
+ quality?: number;
28
+ fullPage?: boolean;
29
+ }) {
30
+ this.browserType = options.browserType || "chromium";
31
+ this.headless = options.headless !== false; // Default to headless
32
+ this.viewport = options.viewport || { width: 1920, height: 1080 };
33
+ this.outputDir = options.outputDir || "./screenshots";
34
+ this.quality = options.quality || 90;
35
+ this.fullPage = options.fullPage !== false; // Default to full page
36
+ }
37
+
38
+ async init() {
39
+ // Create output directory if it doesn't exist
40
+ if (!fs.existsSync(this.outputDir)) {
41
+ fs.mkdirSync(this.outputDir, { recursive: true });
42
+ }
43
+
44
+ // Launch browser based on type
45
+ const browserMap = {
46
+ chromium,
47
+ firefox,
48
+ webkit,
49
+ };
50
+
51
+ const browserClass =
52
+ browserMap[this.browserType as keyof typeof browserMap];
53
+ if (!browserClass) {
54
+ throw new Error(`Unsupported browser type: ${this.browserType}`);
55
+ }
56
+
57
+ this.browser = await browserClass.launch({
58
+ headless: this.headless,
59
+ });
60
+
61
+ this.context = await this.browser.newContext({
62
+ reducedMotion: "reduce",
63
+ deviceScaleFactor: 1,
64
+ });
65
+ }
66
+
67
+ async close() {
68
+ if (this.browser) {
69
+ await this.browser.close();
70
+ }
71
+ }
72
+
73
+ async newPage() {
74
+ if (!this.context) {
75
+ throw new Error("Browser not initialized");
76
+ }
77
+ const page = await this.context?.newPage();
78
+ await page.setViewportSize(this.viewport);
79
+ return page;
80
+ }
81
+
82
+ async goTo(page: Page, url: string) {
83
+ if (!this.context) {
84
+ throw new Error("Browser not initialized");
85
+ }
86
+ await page.goto(url, { waitUntil: "domcontentloaded" });
87
+ }
88
+
89
+ getFilePath(filename: string) {
90
+ const filepath = path.join(this.outputDir, filename);
91
+ return filepath;
92
+ }
93
+
94
+ async takeScreenshot(
95
+ page: Page,
96
+ filename: string,
97
+ options: {
98
+ fullPage?: boolean;
99
+ type?: string;
100
+ quality?: number;
101
+ waitForSelector?: string;
102
+ waitForTimeout?: number;
103
+ } = {}
104
+ ) {
105
+ if (!this.browser) {
106
+ throw new Error("Browser not initialized");
107
+ }
108
+
109
+ try {
110
+ // Wait for selector if specified
111
+ if (options.waitForSelector) {
112
+ console.log(`Waiting for selector: ${options.waitForSelector}`);
113
+ await page.waitForSelector(options.waitForSelector, { timeout: 10000 });
114
+ }
115
+
116
+ // Wait for custom timeout or default
117
+ const waitTime =
118
+ options.waitForTimeout !== undefined ? options.waitForTimeout : 0;
119
+ if (waitTime > 0) {
120
+ console.log(`Waiting for ${waitTime}ms for dynamic content`);
121
+ await page.waitForTimeout(waitTime);
122
+ }
123
+
124
+ // Generate filename
125
+ const filepath = this.getFilePath(filename);
126
+
127
+ // Take screenshot
128
+ const screenshotOptions = {
129
+ path: filepath,
130
+ fullPage:
131
+ (options.fullPage as boolean) !== undefined
132
+ ? options.fullPage
133
+ : this.fullPage,
134
+ type: (options.type as "jpeg" | "png") || "jpeg",
135
+ quality: (options.quality as number) || this.quality,
136
+ } satisfies PageScreenshotOptions;
137
+
138
+ await page.screenshot(screenshotOptions);
139
+
140
+ console.log(`Screenshot saved: ${filepath}`);
141
+ return filepath;
142
+ } catch (error) {
143
+ console.error(
144
+ `Error taking screenshot of ${page.url()}:`,
145
+ (error as Error).message
146
+ );
147
+ throw error;
148
+ } finally {
149
+ await page.close();
150
+ }
151
+ }
152
+
153
+ async takeElementScreenshot(
154
+ page: Page,
155
+ selector: string,
156
+ options: {
157
+ filename?: string;
158
+ fullPage?: boolean;
159
+ type?: string;
160
+ quality?: number;
161
+ } = {}
162
+ ) {
163
+ if (!this.browser) {
164
+ throw new Error("Browser not initialized");
165
+ }
166
+
167
+ try {
168
+ // Wait for element to be visible
169
+ await page.waitForSelector(selector, { timeout: 10000 });
170
+
171
+ const element = await page.$(selector);
172
+ if (!element) {
173
+ throw new Error(`Element not found: ${selector}`);
174
+ }
175
+
176
+ const filename =
177
+ (options.filename as string | undefined) ||
178
+ `${selector.replace(/[^a-zA-Z0-9]/g, "_")}.png`;
179
+ const filepath = this.getFilePath(filename);
180
+
181
+ const elementScreenshotOptions = {
182
+ path: filepath,
183
+ type: (options.type as "jpeg" | "png") || "jpeg",
184
+ quality: (options.quality as number) || this.quality,
185
+ } satisfies PageScreenshotOptions;
186
+
187
+ await element.screenshot(elementScreenshotOptions);
188
+
189
+ console.log(`Element screenshot saved: ${filepath}`);
190
+ return filepath;
191
+ } catch (error) {
192
+ console.error(
193
+ `Error taking element screenshot of ${page.url()}:`,
194
+ (error as Error).message
195
+ );
196
+ throw error;
197
+ } finally {
198
+ await page.close();
199
+ }
200
+ }
201
+
202
+ async batchScreenshots(urls: string[], options = {}) {
203
+ const results: {
204
+ url: string;
205
+ success: boolean;
206
+ filepath: string;
207
+ error?: string;
208
+ }[] = [];
209
+
210
+ for (const url of urls) {
211
+ try {
212
+ const page = await this.newPage();
213
+ await this.goTo(page, url);
214
+ const filepath = await this.takeScreenshot(page, url, options);
215
+ results.push({ url, success: true, filepath });
216
+ } catch (error) {
217
+ results.push({
218
+ url,
219
+ success: false,
220
+ error: (error as Error).message,
221
+ filepath: "",
222
+ });
223
+ }
224
+ }
225
+
226
+ return results;
227
+ }
228
+
229
+ async takeResponsiveScreenshots(
230
+ url: string,
231
+ viewports: { width: number; height: number; name: string }[] = [
232
+ { width: 1920, height: 1080, name: "desktop" },
233
+ { width: 768, height: 1024, name: "tablet" },
234
+ { width: 375, height: 667, name: "mobile" },
235
+ ],
236
+ options: {
237
+ fullPage?: boolean;
238
+ type?: string;
239
+ quality?: number;
240
+ } = {}
241
+ ) {
242
+ if (!this.context) {
243
+ throw new Error("Browser not initialized");
244
+ }
245
+
246
+ const results: {
247
+ viewport: string;
248
+ success: boolean;
249
+ filepath: string;
250
+ error?: string;
251
+ }[] = [];
252
+
253
+ for (const viewport of viewports) {
254
+ try {
255
+ const page = await this.context?.newPage();
256
+ await page.setViewportSize(viewport);
257
+
258
+ await page.goto(url, { waitUntil: "domcontentloaded" });
259
+ await page.waitForTimeout(2000);
260
+
261
+ const filename = `${viewport.name}.png`;
262
+ const filepath = this.getFilePath(filename);
263
+
264
+ const responsiveScreenshotOptions = {
265
+ path: filepath,
266
+ fullPage:
267
+ (options.fullPage as boolean) !== undefined
268
+ ? options.fullPage
269
+ : this.fullPage,
270
+ type: (options.type as "jpeg" | "png") || "png",
271
+ quality: (options.quality as number) || this.quality,
272
+ };
273
+
274
+ await page.screenshot(responsiveScreenshotOptions);
275
+
276
+ await page.close();
277
+
278
+ console.log(`Responsive screenshot saved: ${filepath}`);
279
+ results.push({ viewport: viewport.name, success: true, filepath });
280
+ } catch (error) {
281
+ console.error(
282
+ `Error taking responsive screenshot for ${viewport.name}:`,
283
+ (error as Error).message
284
+ );
285
+ results.push({
286
+ viewport: viewport.name,
287
+ success: false,
288
+ error: (error as Error).message,
289
+ filepath: "",
290
+ });
291
+ }
292
+ }
293
+
294
+ return results;
295
+ }
296
+ }
297
+
298
+ export default ScreenshotTool;
package/src/types.ts ADDED
@@ -0,0 +1,36 @@
1
+ import type { PluginDef, Plugin } from "./plugin";
2
+
3
+ /**
4
+ * Config used in `cappa.config.ts`
5
+ *
6
+ * @example
7
+ * import { defineConfig } from '@cappa/core'
8
+ * export default defineConfig({
9
+ * ...
10
+ * })
11
+ */
12
+ export type UserConfig = {
13
+ /**
14
+ * The project root directory, which can be either an absolute path or a path relative to the location of your `cappa.config.ts` file.
15
+ * @default process.cwd()
16
+ */
17
+ root?: string;
18
+ /**
19
+ * An array of Cappa plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to "pre" for more details.
20
+ */
21
+ plugins?: Array<Plugin | PluginDef>;
22
+ };
23
+
24
+ export type ScreenshotOptions = {
25
+ fullPage?: boolean;
26
+ type?: string;
27
+ quality?: number;
28
+ waitForSelector?: string;
29
+ waitForTimeout?: number;
30
+ };
31
+
32
+ export interface Exposed {
33
+ emitCapture(opt: ScreenshotOptions): void;
34
+ getBaseScreenshotOptions(): ScreenshotOptions;
35
+ waitBrowserMetricsStable(): Promise<void>;
36
+ }
@@ -0,0 +1,13 @@
1
+ export type PossiblePromise<T> = Promise<T> | T;
2
+
3
+ type ArrayWithLength<
4
+ T extends number,
5
+ U extends any[] = []
6
+ > = U["length"] extends T ? U : ArrayWithLength<T, [true, ...U]>;
7
+
8
+ export type GreaterThan<
9
+ T extends number,
10
+ U extends number
11
+ > = ArrayWithLength<U> extends [...ArrayWithLength<T>, ...infer _]
12
+ ? false
13
+ : true;
package/tsconfig.json ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "../../tsconfig.json",
3
+ "include": [
4
+ "src/**/*",
5
+ "./package.json",
6
+ "./tsdown.config.ts",
7
+ "./vitest.config.ts"
8
+ ]
9
+ }
@@ -0,0 +1,11 @@
1
+ import { defineConfig } from "tsdown";
2
+
3
+ export default defineConfig({
4
+ entry: ["src/index.ts"],
5
+ dts: true,
6
+ format: ["esm", "cjs"],
7
+ platform: "node",
8
+ sourcemap: true,
9
+ shims: true,
10
+ exports: true,
11
+ });