cypress-annotate 0.3.0 → 1.0.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.
Files changed (63) hide show
  1. package/AGENTS.md +40 -28
  2. package/CHANGELOG.md +142 -0
  3. package/DOCS/images/crop.png +0 -0
  4. package/DOCS/images/failure-hook.png +0 -0
  5. package/DOCS/internals.md +151 -0
  6. package/README.md +104 -329
  7. package/dist/annotate-image.d.ts +5 -0
  8. package/dist/annotate-image.d.ts.map +1 -1
  9. package/dist/annotate-image.js +16 -2
  10. package/dist/cypress/commands.d.ts +6 -1
  11. package/dist/cypress/commands.d.ts.map +1 -1
  12. package/dist/cypress/commands.js +13 -6
  13. package/dist/cypress/config.d.ts +42 -0
  14. package/dist/cypress/config.d.ts.map +1 -0
  15. package/dist/cypress/config.js +102 -0
  16. package/dist/cypress/failure-hook.d.ts.map +1 -1
  17. package/dist/cypress/failure-hook.js +10 -3
  18. package/dist/cypress/failure-report.d.ts +6 -0
  19. package/dist/cypress/failure-report.d.ts.map +1 -1
  20. package/dist/cypress/failure-report.js +14 -4
  21. package/dist/cypress/task.d.ts +36 -2
  22. package/dist/cypress/task.d.ts.map +1 -1
  23. package/dist/cypress/task.js +60 -5
  24. package/dist/draw.d.ts +4 -0
  25. package/dist/draw.d.ts.map +1 -1
  26. package/dist/draw.js +7 -4
  27. package/dist/index.d.ts +8 -28
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +7 -37
  30. package/dist/types.d.ts +6 -72
  31. package/dist/types.d.ts.map +1 -1
  32. package/package.json +10 -39
  33. package/skills/cypress-annotate/SKILL.md +51 -9
  34. package/DOCS/pipeline.md +0 -308
  35. package/dist/annotate.d.ts +0 -9
  36. package/dist/annotate.d.ts.map +0 -1
  37. package/dist/annotate.js +0 -82
  38. package/dist/browser/collect-elements.js +0 -158
  39. package/dist/browser/measure-target.js +0 -69
  40. package/dist/claude-reasoner.d.ts +0 -17
  41. package/dist/claude-reasoner.d.ts.map +0 -1
  42. package/dist/claude-reasoner.js +0 -192
  43. package/dist/cli.d.ts +0 -2
  44. package/dist/cli.d.ts.map +0 -1
  45. package/dist/cli.js +0 -74
  46. package/dist/cypress/failure-explainer.d.ts +0 -45
  47. package/dist/cypress/failure-explainer.d.ts.map +0 -1
  48. package/dist/cypress/failure-explainer.js +0 -123
  49. package/dist/finder.d.ts +0 -68
  50. package/dist/finder.d.ts.map +0 -1
  51. package/dist/finder.js +0 -64
  52. package/dist/inventory.d.ts +0 -33
  53. package/dist/inventory.d.ts.map +0 -1
  54. package/dist/inventory.js +0 -88
  55. package/dist/measure.d.ts +0 -11
  56. package/dist/measure.d.ts.map +0 -1
  57. package/dist/measure.js +0 -145
  58. package/dist/pipeline.d.ts +0 -60
  59. package/dist/pipeline.d.ts.map +0 -1
  60. package/dist/pipeline.js +0 -115
  61. package/skills/annotate-bug/SKILL.md +0 -121
  62. package/src/browser/collect-elements.js +0 -158
  63. package/src/browser/measure-target.js +0 -69
@@ -0,0 +1,42 @@
1
+ import type { AnnotationStyle, ShapeKind } from '../types.js';
2
+ /**
3
+ * Project-wide defaults, read from `env.annotate` in cypress.config.
4
+ *
5
+ * export default defineConfig({
6
+ * env: {
7
+ * annotate: {
8
+ * style: { color: '#7C3AED', strokeWidth: 4 },
9
+ * },
10
+ * },
11
+ * });
12
+ *
13
+ * Cypress serialises `env` into the browser, so one block reaches cy.annotate()
14
+ * and the failure hook alike, and `CYPRESS_annotate='{"style":{...}}'` overrides
15
+ * it for a single CI job without a second mechanism to learn.
16
+ *
17
+ * Everything here is also settable per call, and the per-call value wins.
18
+ */
19
+ export interface AnnotateEnvConfig {
20
+ style?: AnnotationStyle;
21
+ shape?: ShapeKind;
22
+ /** Crop to the annotated element rather than keeping the whole viewport. */
23
+ crop?: boolean;
24
+ cropPadding?: number;
25
+ /** Write `<name>.raw.png` beside every annotated shot, for diffing. */
26
+ keepRaw?: boolean;
27
+ /** Leave this many CSS px above an element that had to be scrolled to. */
28
+ scrollOffset?: number;
29
+ /** One JSON record per annotated screenshot. Default out/cypress/annotations.json. */
30
+ manifestPath?: string;
31
+ /** Where failure records accumulate. Default out/cypress/failures.json. */
32
+ reportPath?: string;
33
+ }
34
+ export declare const DEFAULT_MANIFEST_PATH = "out/cypress/annotations.json";
35
+ export declare const DEFAULT_REPORT_PATH = "out/cypress/failures.json";
36
+ /**
37
+ * Reads and validates `Cypress.env('annotate')`. A typo is reported rather than
38
+ * silently dropped, because a theme that quietly does nothing is worse than one
39
+ * that says why.
40
+ */
41
+ export declare function readAnnotateConfig(): AnnotateEnvConfig;
42
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/cypress/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AACpE,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAwE/D;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,iBAAiB,CA8BtD"}
@@ -0,0 +1,102 @@
1
+ export const DEFAULT_MANIFEST_PATH = 'out/cypress/annotations.json';
2
+ export const DEFAULT_REPORT_PATH = 'out/cypress/failures.json';
3
+ const STYLE_KEYS = {
4
+ color: 'string',
5
+ strokeWidth: 'number',
6
+ padding: 'number',
7
+ radius: 'number',
8
+ dimOutside: 'number',
9
+ labelFontSize: 'number',
10
+ labelColor: 'string',
11
+ labelBackground: 'string',
12
+ labelFontFamily: 'string',
13
+ labelFontWeight: 'string|number',
14
+ };
15
+ const TOP_LEVEL_KEYS = {
16
+ style: 'object',
17
+ shape: 'string',
18
+ crop: 'boolean',
19
+ cropPadding: 'number',
20
+ keepRaw: 'boolean',
21
+ scrollOffset: 'number',
22
+ manifestPath: 'string',
23
+ reportPath: 'string',
24
+ };
25
+ const SHAPES = ['box', 'circle', 'arrow'];
26
+ // One warning per distinct problem per run. An afterEach hook would otherwise
27
+ // repeat the same typo once per test, which buries the run's real output.
28
+ const warned = new Set();
29
+ function warn(message) {
30
+ if (warned.has(message))
31
+ return;
32
+ warned.add(message);
33
+ // Cypress.log is unavailable outside a test body, so console is the floor.
34
+ if (typeof Cypress !== 'undefined' && typeof Cypress.log === 'function') {
35
+ Cypress.log({ name: 'annotate', message: `! ${message}` });
36
+ }
37
+ console.warn(`cypress-annotate: ${message}`);
38
+ }
39
+ function typeOf(value) {
40
+ return Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
41
+ }
42
+ function validateStyle(raw) {
43
+ const style = {};
44
+ for (const [key, value] of Object.entries(raw)) {
45
+ const expected = STYLE_KEYS[key];
46
+ if (!expected) {
47
+ warn(`env.annotate.style.${key} is not a style option and was ignored. Valid: ${Object.keys(STYLE_KEYS).join(', ')}.`);
48
+ continue;
49
+ }
50
+ const actual = typeOf(value);
51
+ if (expected === 'string|number' ? actual !== 'string' && actual !== 'number' : actual !== expected) {
52
+ warn(`env.annotate.style.${key} should be a ${expected} but was a ${actual}; ignored.`);
53
+ continue;
54
+ }
55
+ if (key === 'dimOutside' && (value < 0 || value > 1)) {
56
+ warn(`env.annotate.style.dimOutside should be between 0 and 1 but was ${String(value)}; ignored.`);
57
+ continue;
58
+ }
59
+ if (expected === 'number' && value < 0) {
60
+ warn(`env.annotate.style.${key} should not be negative but was ${String(value)}; ignored.`);
61
+ continue;
62
+ }
63
+ style[key] = value;
64
+ }
65
+ return style;
66
+ }
67
+ /**
68
+ * Reads and validates `Cypress.env('annotate')`. A typo is reported rather than
69
+ * silently dropped, because a theme that quietly does nothing is worse than one
70
+ * that says why.
71
+ */
72
+ export function readAnnotateConfig() {
73
+ const raw = typeof Cypress === 'undefined' ? undefined : Cypress.env('annotate');
74
+ if (raw === undefined || raw === null)
75
+ return {};
76
+ if (typeOf(raw) !== 'object') {
77
+ warn(`env.annotate should be an object but was a ${typeOf(raw)}; ignored.`);
78
+ return {};
79
+ }
80
+ const config = {};
81
+ for (const [key, value] of Object.entries(raw)) {
82
+ const expected = TOP_LEVEL_KEYS[key];
83
+ if (!expected) {
84
+ warn(`env.annotate.${key} is not an option and was ignored. Valid: ${Object.keys(TOP_LEVEL_KEYS).join(', ')}.`);
85
+ continue;
86
+ }
87
+ if (typeOf(value) !== expected) {
88
+ warn(`env.annotate.${key} should be a ${expected} but was a ${typeOf(value)}; ignored.`);
89
+ continue;
90
+ }
91
+ if (key === 'style') {
92
+ config.style = validateStyle(value);
93
+ continue;
94
+ }
95
+ if (key === 'shape' && !SHAPES.includes(value)) {
96
+ warn(`env.annotate.shape should be one of ${SHAPES.join(', ')} but was "${String(value)}"; ignored.`);
97
+ continue;
98
+ }
99
+ config[key] = value;
100
+ }
101
+ return config;
102
+ }
@@ -1 +1 @@
1
- {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,aAAa,CAAC;AAGhE,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CA4IhF"}
1
+ {"version":3,"file":"failure-hook.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAe,MAAM,aAAa,CAAC;AAGhE,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAmJhF"}
@@ -2,7 +2,7 @@
2
2
  import { describeFailure, recoverFailure } from './failure-selector.js';
3
3
  import { collectInventory, measureTargets, readMetrics } from './measure-dom.js';
4
4
  import { isFullyVisible, scrollIntoViewIfNeeded } from './scroll-into-view.js';
5
- const DEFAULT_REPORT_PATH = 'out/cypress/failures.json';
5
+ import { readAnnotateConfig, DEFAULT_REPORT_PATH } from './config.js';
6
6
  function slugify(text) {
7
7
  return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase().slice(0, 60) || 'failure';
8
8
  }
@@ -29,10 +29,13 @@ function slugify(text) {
29
29
  * and it becomes ambiguous which one the DOM measurement actually matches.
30
30
  */
31
31
  export function registerFailureCapture(options = {}) {
32
- const reportPath = options.reportPath ?? DEFAULT_REPORT_PATH;
33
32
  afterEach(function () {
34
33
  if (this.currentTest?.state !== 'failed')
35
34
  return;
35
+ // Read inside the hook rather than at registration: the support file is
36
+ // evaluated before Cypress has finished setting up env for the spec.
37
+ const defaults = readAnnotateConfig();
38
+ const reportPath = options.reportPath ?? defaults.reportPath ?? DEFAULT_REPORT_PATH;
36
39
  // Read failure state before issuing any cy.* command below - those mutate
37
40
  // cy.state('current'), so this has to happen first and synchronously.
38
41
  const err = this.currentTest.err;
@@ -109,7 +112,11 @@ export function registerFailureCapture(options = {}) {
109
112
  measurement: { metrics, targets: [target] },
110
113
  labels: [label],
111
114
  capture: 'viewport',
112
- style: options.style,
115
+ style: { ...defaults.style, ...options.style },
116
+ keepRaw: defaults.keepRaw,
117
+ manifestPath: defaults.manifestPath,
118
+ spec: Cypress.spec.relative,
119
+ test: testTitle,
113
120
  });
114
121
  })
115
122
  .then((annotateResult) => {
@@ -37,5 +37,11 @@ export interface AppendFailureArgs {
37
37
  reportPath: string;
38
38
  record: FailureRecord;
39
39
  }
40
+ /**
41
+ * Append one record to a JSON array on disk, creating the file and its parent
42
+ * directory if neither exists. Read-modify-write is safe here because Cypress
43
+ * runs tasks one at a time, in the single Node process behind the run.
44
+ */
45
+ export declare function appendRecord<T>(path: string, record: T): Promise<void>;
40
46
  export declare function appendFailureRecord({ reportPath, record }: AppendFailureArgs): Promise<null>;
41
47
  //# sourceMappingURL=failure-report.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"failure-report.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,wBAAsB,mBAAmB,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlG"}
1
+ {"version":3,"file":"failure-report.d.ts","sourceRoot":"","sources":["../../src/cypress/failure-report.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,iFAAiF;IACjF,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E;AAED,wBAAsB,mBAAmB,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlG"}
@@ -1,14 +1,24 @@
1
- import { readFile, writeFile } from 'node:fs/promises';
2
- export async function appendFailureRecord({ reportPath, record }) {
1
+ import { mkdir, readFile, writeFile } from 'node:fs/promises';
2
+ import { dirname } from 'node:path';
3
+ /**
4
+ * Append one record to a JSON array on disk, creating the file and its parent
5
+ * directory if neither exists. Read-modify-write is safe here because Cypress
6
+ * runs tasks one at a time, in the single Node process behind the run.
7
+ */
8
+ export async function appendRecord(path, record) {
3
9
  let existing = [];
4
10
  try {
5
- existing = JSON.parse(await readFile(reportPath, 'utf8'));
11
+ existing = JSON.parse(await readFile(path, 'utf8'));
6
12
  }
7
13
  catch (error) {
8
14
  if (error.code !== 'ENOENT')
9
15
  throw error;
16
+ await mkdir(dirname(path), { recursive: true });
10
17
  }
11
18
  existing.push(record);
12
- await writeFile(reportPath, JSON.stringify(existing, null, 2));
19
+ await writeFile(path, JSON.stringify(existing, null, 2));
20
+ }
21
+ export async function appendFailureRecord({ reportPath, record }) {
22
+ await appendRecord(reportPath, record);
13
23
  return null;
14
24
  }
@@ -20,6 +20,28 @@ export interface AnnotateTaskArgs {
20
20
  outPath?: string;
21
21
  /** Also keep the un-annotated pixels, at `<out>.raw.png`. */
22
22
  keepRaw?: boolean;
23
+ /** Where to record what was annotated. Defaults to out/cypress/annotations.json. */
24
+ manifestPath?: string;
25
+ /** Spec and test the annotation came from. Only used for the manifest. */
26
+ spec?: string;
27
+ test?: string;
28
+ }
29
+ /**
30
+ * One line of the run's manifest. CI wants a list of what was produced without
31
+ * having to walk the screenshots folder and guess which files are ours, and a
32
+ * ticket wants to know which test a given image came from.
33
+ */
34
+ export interface AnnotationRecord {
35
+ spec: string | null;
36
+ test: string | null;
37
+ labels: string[];
38
+ outPath: string;
39
+ rawPath: string | null;
40
+ width: number;
41
+ height: number;
42
+ drawnRects: PixelRect[];
43
+ warnings: string[];
44
+ timestamp: string;
23
45
  }
24
46
  export interface AnnotateTaskResult {
25
47
  outPath: string;
@@ -38,10 +60,22 @@ export declare function annotateScreenshot(args: AnnotateTaskArgs): Promise<Anno
38
60
  * any of those overloads; the narrowing cast is contained below.
39
61
  */
40
62
  export type CypressPluginOn = (...args: never[]) => unknown;
63
+ /** The `config` half of setupNodeEvents. Accepted for forwards compatibility. */
64
+ export interface AnnotateSetupConfig {
65
+ env?: Record<string, unknown>;
66
+ }
41
67
  /**
42
68
  * Register in cypress.config setupNodeEvents:
43
69
  *
44
- * setupNodeEvents(on) { registerAnnotateTasks(on); }
70
+ * setupNodeEvents(on, config) { registerAnnotateTasks(on, config); }
71
+ *
72
+ * Deliberately registers nothing but tasks. Cypress allows one handler per run
73
+ * event and silently keeps the last one registered, so taking `before:run` or
74
+ * `after:run` here would quietly stop a project's own handler from firing. The
75
+ * manifest and the job summary are driven from the task instead, which can be
76
+ * registered alongside anything.
77
+ *
78
+ * `config` is optional and currently unused.
45
79
  */
46
- export declare function registerAnnotateTasks(on: CypressPluginOn): void;
80
+ export declare function registerAnnotateTasks(on: CypressPluginOn, _config?: AnnotateSetupConfig): void;
47
81
  //# sourceMappingURL=task.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8D5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,CAQ/D"}
1
+ {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/cypress/task.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAwCD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4E5F;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAI5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAQ9F"}
@@ -1,6 +1,40 @@
1
- import { readFile, writeFile } from 'node:fs/promises';
1
+ import { appendFile, readFile, rm, writeFile } from 'node:fs/promises';
2
+ import { relative } from 'node:path';
2
3
  import { annotateImage } from '../annotate-image.js';
3
- import { appendFailureRecord } from './failure-report.js';
4
+ import { appendFailureRecord, appendRecord } from './failure-report.js';
5
+ import { DEFAULT_MANIFEST_PATH } from './config.js';
6
+ /**
7
+ * Manifest paths already written to by this process. Cypress runs the whole of
8
+ * `cypress run` in one Node process, so "first write of the process" is the
9
+ * run boundary, and using it means no before:run handler is needed to clear
10
+ * last run's records.
11
+ */
12
+ const manifestsStarted = new Set();
13
+ /** Whether the job summary's table header has been written yet this process. */
14
+ let summaryStarted = false;
15
+ async function appendStepSummary(record) {
16
+ const summaryPath = process.env.GITHUB_STEP_SUMMARY;
17
+ if (!summaryPath)
18
+ return;
19
+ const label = record.labels.join('; ') || '-';
20
+ const warnings = record.warnings.length > 0 ? ` (${record.warnings.length} warning(s))` : '';
21
+ const row = `| ${record.test ?? record.spec ?? '-'} ` +
22
+ `| ${label.replace(/\|/g, '\\|')} ` +
23
+ `| \`${relative(process.cwd(), record.outPath)}\`${warnings} |\n`;
24
+ const header = summaryStarted
25
+ ? ''
26
+ : '### Annotated screenshots\n\n| Test | Label | Image |\n| --- | --- | --- |\n';
27
+ summaryStarted = true;
28
+ await appendFile(summaryPath, header + row);
29
+ }
30
+ async function recordAnnotation(manifestPath, record) {
31
+ if (!manifestsStarted.has(manifestPath)) {
32
+ manifestsStarted.add(manifestPath);
33
+ await rm(manifestPath, { force: true });
34
+ }
35
+ await appendRecord(manifestPath, record);
36
+ await appendStepSummary(record);
37
+ }
4
38
  export async function annotateScreenshot(args) {
5
39
  const { screenshotPath, measurement } = args;
6
40
  if (!screenshotPath)
@@ -46,6 +80,19 @@ export async function annotateScreenshot(args) {
46
80
  await writeFile(rawPath, result.rawImage);
47
81
  }
48
82
  await writeFile(outPath, result.image);
83
+ const warningsOut = [...warnings, ...result.warnings];
84
+ await recordAnnotation(args.manifestPath ?? DEFAULT_MANIFEST_PATH, {
85
+ spec: args.spec ?? null,
86
+ test: args.test ?? null,
87
+ labels: (args.labels ?? []).filter((label) => Boolean(label)),
88
+ outPath,
89
+ rawPath,
90
+ width: result.width,
91
+ height: result.height,
92
+ drawnRects: result.drawnRects,
93
+ warnings: warningsOut,
94
+ timestamp: new Date().toISOString(),
95
+ });
49
96
  return {
50
97
  outPath,
51
98
  rawPath,
@@ -53,15 +100,23 @@ export async function annotateScreenshot(args) {
53
100
  height: result.height,
54
101
  scale: result.scale,
55
102
  drawnRects: result.drawnRects,
56
- warnings: [...warnings, ...result.warnings],
103
+ warnings: warningsOut,
57
104
  };
58
105
  }
59
106
  /**
60
107
  * Register in cypress.config setupNodeEvents:
61
108
  *
62
- * setupNodeEvents(on) { registerAnnotateTasks(on); }
109
+ * setupNodeEvents(on, config) { registerAnnotateTasks(on, config); }
110
+ *
111
+ * Deliberately registers nothing but tasks. Cypress allows one handler per run
112
+ * event and silently keeps the last one registered, so taking `before:run` or
113
+ * `after:run` here would quietly stop a project's own handler from firing. The
114
+ * manifest and the job summary are driven from the task instead, which can be
115
+ * registered alongside anything.
116
+ *
117
+ * `config` is optional and currently unused.
63
118
  */
64
- export function registerAnnotateTasks(on) {
119
+ export function registerAnnotateTasks(on, _config) {
65
120
  on('task', {
66
121
  annotateScreenshot: ((args) => annotateScreenshot(args)),
67
122
  appendFailureRecord: ((args) => appendFailureRecord(args)),
package/dist/draw.d.ts CHANGED
@@ -7,6 +7,9 @@ export interface ResolvedStyle {
7
7
  dimOutside: number;
8
8
  labelFontSize: number;
9
9
  labelColor: string;
10
+ labelBackground: string;
11
+ labelFontFamily: string;
12
+ labelFontWeight: string | number;
10
13
  }
11
14
  export interface DrawSpec {
12
15
  rect: PixelRect;
@@ -14,6 +17,7 @@ export interface DrawSpec {
14
17
  shape: ShapeKind;
15
18
  style: ResolvedStyle;
16
19
  }
20
+ export declare const DEFAULT_FONT_STACK = "-apple-system, 'Helvetica Neue', Helvetica, Arial, sans-serif";
17
21
  export declare function buildOverlaySvg(width: number, height: number, specs: DrawSpec[]): string;
18
22
  export declare function compositeOverlay(screenshot: Buffer, svg: string): Promise<Buffer>;
19
23
  //# sourceMappingURL=draw.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;CACtB;AAuLD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAsCxF;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvF"}
1
+ {"version":3,"file":"draw.d.ts","sourceRoot":"","sources":["../src/draw.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,kEACkC,CAAC;AAwLlE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAsCxF;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvF"}
package/dist/draw.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import sharp from 'sharp';
2
- const FONT_STACK = "-apple-system, 'Helvetica Neue', Helvetica, Arial, sans-serif";
2
+ export const DEFAULT_FONT_STACK = "-apple-system, 'Helvetica Neue', Helvetica, Arial, sans-serif";
3
3
  function escapeXml(text) {
4
4
  return text.replace(/[<>&'"]/g, (c) => {
5
5
  switch (c) {
@@ -16,7 +16,9 @@ function round(n) {
16
16
  }
17
17
  /**
18
18
  * Approximate rendered text width. librsvg gives us no measurement API, so the
19
- * label pill is sized from an average glyph ratio and generous padding.
19
+ * label pill is sized from an average glyph ratio and generous padding. The
20
+ * ratio is tuned for the default sans stack, so a very wide or very narrow
21
+ * custom family will wrap a little early or a little late.
20
22
  */
21
23
  function estimateTextWidth(text, fontSize) {
22
24
  return text.length * fontSize * 0.58;
@@ -102,8 +104,9 @@ function labelShape(text, rect, style, imageWidth, imageHeight, centerOnAnchor =
102
104
  .map((line, i) => `<tspan x="${round(pillX + padX)}" y="${round(firstBaseline + i * lineHeight)}">${escapeXml(line)}</tspan>`)
103
105
  .join('');
104
106
  return (`<rect x="${round(pillX)}" y="${round(pillY)}" width="${round(pillWidth)}" height="${round(pillHeight)}" ` +
105
- `rx="${round(Math.min(pillHeight / 2, fontSize * 0.5))}" fill="${escapeXml(style.color)}" />` +
106
- `<text font-family="${FONT_STACK}" font-size="${round(fontSize)}" font-weight="600" ` +
107
+ `rx="${round(Math.min(pillHeight / 2, fontSize * 0.5))}" fill="${escapeXml(style.labelBackground)}" />` +
108
+ `<text font-family="${escapeXml(style.labelFontFamily)}" font-size="${round(fontSize)}" ` +
109
+ `font-weight="${escapeXml(String(style.labelFontWeight))}" ` +
107
110
  `fill="${escapeXml(style.labelColor)}" xml:space="preserve">${tspans}</text>`);
108
111
  }
109
112
  /** Greedy word wrap against the same glyph-ratio estimate used for the pill. */
package/dist/index.d.ts CHANGED
@@ -1,32 +1,12 @@
1
- import type { Annotation, AnnotateOptions, AnnotateResult } from './types.js';
2
- import type { LaunchOptions } from 'playwright';
3
- export { annotate } from './annotate.js';
4
- export { annotateImage, resolveScale, type AnnotateImageOptions, type AnnotateImageResult, type MeasuredTarget, } from './annotate-image.js';
5
- export { measureElement, measureRegion, readPageMetrics } from './measure.js';
6
- export { buildOverlaySvg, compositeOverlay } from './draw.js';
7
- export { collectInventory, renderInventory, type InventoryItem } from './inventory.js';
8
- export { findingsToAnnotations, gatherReasonerInput, ReplayReasoner, SEVERITY_COLORS, type BugFinding, type Reasoner, type ReasonerInput, type ResolvedFinding, type ResolvedFindings, type Severity, } from './finder.js';
9
- export { runBugHunt, type BugHuntOptions, type BugHuntResult } from './pipeline.js';
10
- export type * from './types.js';
11
- export interface CaptureOptions extends AnnotateOptions {
12
- viewport?: {
13
- width: number;
14
- height: number;
15
- };
16
- deviceScaleFactor?: number;
17
- headless?: boolean;
18
- /** Extra settling time after load, in ms, for pages that animate in. */
19
- settleMs?: number;
20
- launch?: LaunchOptions;
21
- }
22
1
  /**
23
- * One-shot: open a URL, annotate it, close the browser.
2
+ * The driver-agnostic half of the plugin.
24
3
  *
25
- * Playwright is loaded lazily, on the first call, rather than imported at the
26
- * top of this file. `playwright` is an optional peer dependency - a consumer
27
- * who only wants annotateImage()/the Cypress plugin (neither of which touch a
28
- * browser at all) should never be forced to have it installed just because
29
- * this function exists somewhere else in the same package.
4
+ * Everything here works on a PNG somebody else captured, so it never opens a
5
+ * browser and never touches Cypress. The Cypress task goes through it, and so
6
+ * can anything else that can produce a screenshot, the page metrics that were
7
+ * true when it was taken, and rectangles in CSS pixels.
30
8
  */
31
- export declare function captureAnnotated(url: string, annotations: Annotation[], options?: CaptureOptions): Promise<AnnotateResult>;
9
+ export { annotateImage, resolveScale, resolveStyle, type AnnotateImageOptions, type AnnotateImageResult, type MeasuredTarget, } from './annotate-image.js';
10
+ export { buildOverlaySvg, compositeOverlay } from './draw.js';
11
+ export type * from './types.js';
32
12
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAW,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKvF,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpF,mBAAmB,YAAY,CAAC;AAEhC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAgBzB"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,mBAAmB,YAAY,CAAC"}
package/dist/index.js CHANGED
@@ -1,40 +1,10 @@
1
- import { annotate } from './annotate.js';
2
- export { annotate } from './annotate.js';
3
- export { annotateImage, resolveScale, } from './annotate-image.js';
4
- export { measureElement, measureRegion, readPageMetrics } from './measure.js';
5
- export { buildOverlaySvg, compositeOverlay } from './draw.js';
6
- export { collectInventory, renderInventory } from './inventory.js';
7
- // ClaudeReasoner is not re-exported here - import it from 'cypress-annotate/reasoner'
8
- // instead. It is the only piece of this package with a real (non-type-only)
9
- // dependency on @anthropic-ai/sdk; keeping it out of this barrel means every
10
- // other export here stays usable with neither the SDK nor a peer install of it.
11
- export { findingsToAnnotations, gatherReasonerInput, ReplayReasoner, SEVERITY_COLORS, } from './finder.js';
12
- export { runBugHunt } from './pipeline.js';
13
1
  /**
14
- * One-shot: open a URL, annotate it, close the browser.
2
+ * The driver-agnostic half of the plugin.
15
3
  *
16
- * Playwright is loaded lazily, on the first call, rather than imported at the
17
- * top of this file. `playwright` is an optional peer dependency - a consumer
18
- * who only wants annotateImage()/the Cypress plugin (neither of which touch a
19
- * browser at all) should never be forced to have it installed just because
20
- * this function exists somewhere else in the same package.
4
+ * Everything here works on a PNG somebody else captured, so it never opens a
5
+ * browser and never touches Cypress. The Cypress task goes through it, and so
6
+ * can anything else that can produce a screenshot, the page metrics that were
7
+ * true when it was taken, and rectangles in CSS pixels.
21
8
  */
22
- export async function captureAnnotated(url, annotations, options = {}) {
23
- let browser;
24
- try {
25
- const { chromium } = await import('playwright');
26
- browser = await chromium.launch({ headless: options.headless ?? true, ...options.launch });
27
- const context = await browser.newContext({
28
- viewport: options.viewport ?? { width: 1280, height: 800 },
29
- deviceScaleFactor: options.deviceScaleFactor ?? 2,
30
- });
31
- const page = await context.newPage();
32
- await page.goto(url, { waitUntil: 'networkidle' });
33
- if (options.settleMs)
34
- await page.waitForTimeout(options.settleMs);
35
- return await annotate(page, annotations, options);
36
- }
37
- finally {
38
- await browser?.close();
39
- }
40
- }
9
+ export { annotateImage, resolveScale, resolveStyle, } from './annotate-image.js';
10
+ export { buildOverlaySvg, compositeOverlay } from './draw.js';
package/dist/types.d.ts CHANGED
@@ -25,37 +25,6 @@ export interface PageMetrics {
25
25
  documentWidth: number;
26
26
  documentHeight: number;
27
27
  }
28
- /**
29
- * Fallback target for when the agent cannot name a clean selector: a rectangle
30
- * given as percentages, so it is independent of viewport size.
31
- */
32
- export interface Region {
33
- xPct: number;
34
- yPct: number;
35
- widthPct: number;
36
- heightPct: number;
37
- /** Percentages of the viewport (default) or of the whole document. */
38
- basis?: 'viewport' | 'document';
39
- }
40
- export interface MeasuredElement {
41
- /** Human-readable description of what was targeted. */
42
- selector: string;
43
- /** Whether this came from a selector match or a percentage region. */
44
- source: 'selector' | 'region';
45
- /** Viewport-relative, CSS px, including any ancestor-iframe offsets. */
46
- viewportRect: CssRect;
47
- /** Document-relative, CSS px (viewportRect + scroll, except for fixed elements). */
48
- documentRect: CssRect;
49
- /** True if the element or an ancestor is position:fixed, so it does not scroll. */
50
- isFixed: boolean;
51
- /** True if any part of the element is inside the current viewport. */
52
- inViewport: boolean;
53
- /** Extra frames the element was found inside, outermost first. */
54
- framePath: string[];
55
- tagName: string;
56
- /** How many elements the selector matched. Anything above 1 is ambiguous. */
57
- matchCount: number;
58
- }
59
28
  export type ShapeKind = 'box' | 'circle' | 'arrow';
60
29
  export interface AnnotationStyle {
61
30
  /** CSS colour for the outline and label background. */
@@ -70,46 +39,11 @@ export interface AnnotationStyle {
70
39
  dimOutside?: number;
71
40
  labelFontSize?: number;
72
41
  labelColor?: string;
73
- }
74
- export interface Annotation {
75
- /**
76
- * CSS selector, or a frame chain like ["iframe#checkout", ".pay-button"].
77
- * Mutually exclusive with `region`; exactly one must be set.
78
- */
79
- selector?: string | string[];
80
- /** Percentage-based fallback when no selector is available. */
81
- region?: Region;
82
- label?: string;
83
- shape?: ShapeKind;
84
- style?: AnnotationStyle;
85
- }
86
- export type ScreenshotMode = 'viewport' | 'fullPage' | 'element';
87
- export interface AnnotateOptions {
88
- /** Where to screenshot: the viewport, the whole document, or a crop around the element. */
89
- mode?: ScreenshotMode;
90
- /** For mode 'element', how much context to keep around the element, in CSS px. */
91
- cropPadding?: number;
92
- /**
93
- * Scroll to the top before capturing a full-page screenshot. Chromium renders
94
- * fixed elements once, at whatever scroll offset the capture starts from, so
95
- * starting at the top is the only offset where fixed and static elements agree.
96
- */
97
- scrollToTop?: boolean;
98
- /** Bring the first annotated element into view before a viewport capture. */
99
- scrollIntoView?: boolean;
100
- style?: AnnotationStyle;
101
- }
102
- export interface AnnotateResult {
103
- image: Buffer;
104
- /** The same capture without the overlay, cropped identically. For verification. */
105
- rawImage: Buffer;
106
- /** Pixel dimensions of the returned image. */
107
- width: number;
108
- height: number;
109
- metrics: PageMetrics;
110
- elements: MeasuredElement[];
111
- /** Final drawn rectangles, in image pixels. Useful for asserting alignment. */
112
- drawnRects: PixelRect[];
113
- warnings: string[];
42
+ /** Label pill background. Defaults to `color`, so one value themes both. */
43
+ labelBackground?: string;
44
+ /** CSS font-family for the label. */
45
+ labelFontFamily?: string;
46
+ /** CSS font-weight for the label. */
47
+ labelFontWeight?: string | number;
114
48
  }
115
49
  //# sourceMappingURL=types.d.ts.map