cypress-annotate 0.4.0 → 1.1.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 +174 -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 -352
  7. package/dist/annotate-image.d.ts +19 -2
  8. package/dist/annotate-image.d.ts.map +1 -1
  9. package/dist/annotate-image.js +55 -12
  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 +20 -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 +17 -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 +39 -3
  22. package/dist/cypress/task.d.ts.map +1 -1
  23. package/dist/cypress/task.js +61 -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 +9 -20
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +7 -57
  30. package/dist/types.d.ts +13 -69
  31. package/dist/types.d.ts.map +1 -1
  32. package/package.json +11 -43
  33. package/skills/cypress-annotate/SKILL.md +62 -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 -3
  44. package/dist/cli.d.ts.map +0 -1
  45. package/dist/cli.js +0 -84
  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
package/DOCS/pipeline.md DELETED
@@ -1,308 +0,0 @@
1
- # The Playwright pipeline and the reasoning layer
2
-
3
- Two things ship in `cypress-annotate` that the Cypress plugin never touches: a
4
- general Playwright-driven annotation pipeline, and a Claude-based reasoning layer
5
- that looks at a page and works out *what's* wrong before drawing the box. This
6
- document covers both. For the Cypress plugin, see the [README](../README.md).
7
-
8
- Both are optional. `playwright` and `@anthropic-ai/sdk` are optional
9
- `peerDependencies`, so install whichever your own usage calls into:
10
-
11
- ```bash
12
- npm install playwright @anthropic-ai/sdk
13
- npx playwright install chromium
14
- ```
15
-
16
- The repo's own suites for this half:
17
-
18
- ```bash
19
- npm run verify # coordinate-pipeline alignment suite, 20 cases
20
- npm run verify:image # driver-agnostic (MCP) alignment suite, 10 cases
21
- npm run test:reasoner # Claude reasoning request/parse suite, 12 cases, no API key needed
22
- npm run demo # end-to-end on the buggy fixture, using recorded findings
23
- npm run annotate -- --url https://example.com --selector 'a' --label 'Broken link'
24
- ```
25
-
26
- ## API
27
-
28
- ```ts
29
- import { captureAnnotated } from 'cypress-annotate';
30
-
31
- const result = await captureAnnotated('https://example.com', [
32
- { selector: '#submit', label: 'Misaligned by 12px', shape: 'box' },
33
- { selector: ['iframe#checkout', '.pay-button'], label: 'Overlaps' },
34
- ], { mode: 'element', cropPadding: 80, style: { dimOutside: 0.5 } });
35
-
36
- await writeFile('bug.png', result.image);
37
- console.log(result.elements, result.drawnRects, result.warnings);
38
- ```
39
-
40
- `captureAnnotated()` is the only export in the package that launches a browser,
41
- and it imports playwright lazily on first call. `annotateImage`, `runBugHunt`,
42
- and `findingsToAnnotations` all work with no browser installed.
43
-
44
- Or drive an existing Playwright page directly with
45
- `annotate(page, annotations, options)`. That's the entry point the reasoning step
46
- uses, since the agent already has a page open.
47
-
48
- **Modes.** `viewport` captures what's on screen, scrolling the first target into
49
- view first. `fullPage` captures the whole document. `element` captures full-page
50
- then crops to the annotated region plus `cropPadding`, which is usually the most
51
- useful thing to attach to a ticket.
52
-
53
- **Result.** Alongside `image`, you get `rawImage` (same capture, same crop, no
54
- overlay), the measured `elements`, the final `drawnRects` in image pixels, and
55
- `warnings`.
56
-
57
- **Warnings worth acting on:** selector matched more than one element, element has
58
- a zero-sized box, element is outside the viewport, element is fixed during a
59
- full-page capture.
60
-
61
- ### Annotating an image somebody else captured
62
-
63
- `annotateImage()` is the one export here that never opens a browser and knows
64
- nothing about any driver. Give it a PNG, the page metrics that were true when it
65
- was taken, and rectangles in CSS pixels. The Cypress plugin and the MCP path both
66
- go through it, and so can anything else that can produce those three things.
67
-
68
- ```ts
69
- import { annotateImage } from 'cypress-annotate';
70
- import { readFile, writeFile } from 'node:fs/promises';
71
-
72
- const result = await annotateImage(
73
- await readFile('shot.png'),
74
- [{
75
- // Viewport-relative CSS px, straight from getBoundingClientRect().
76
- viewportRect: { x: 100, y: 100, width: 320, height: 90 },
77
- label: 'Apply button escapes its card',
78
- }],
79
- {
80
- metrics: {
81
- devicePixelRatio: 2,
82
- scrollX: 0,
83
- scrollY: 0,
84
- viewportWidth: 1280,
85
- viewportHeight: 800,
86
- documentWidth: 1280,
87
- documentHeight: 4200,
88
- },
89
- capture: 'viewport',
90
- },
91
- );
92
-
93
- await writeFile('annotated.png', result.image);
94
- console.log(result.scale, result.drawnRects, result.warnings);
95
- ```
96
-
97
- The argument list is positional, `(screenshot, targets, options)`, and the
98
- metrics are the four dimensions plus scroll and dpr. Both are easy to get wrong
99
- from the type names alone, which is why the example is here.
100
-
101
- `devicePixelRatio` is treated as a hint rather than a fact. `resolveScale()`
102
- compares the image against the viewport it was supposed to cover and uses the
103
- measured ratio when the two disagree, because a screenshot that was downscaled
104
- behind your back is exactly what makes a box drift. Whatever it settles on comes
105
- back as `result.scale`, and a mismatch lands in `result.warnings`.
106
-
107
- Set `isFixed: true` on a target whose element is `position: fixed`, so it gets no
108
- scroll correction. Pass `documentRect` yourself only when the viewport rect and
109
- the scroll offset are not enough to derive it.
110
-
111
- ### The region fallback
112
-
113
- When no element corresponds to the problem (blank space where something should
114
- be), a target can be a rectangle in percentages instead:
115
-
116
- ```ts
117
- { region: { xPct: 10, yPct: 50, widthPct: 30, heightPct: 8, basis: 'viewport' } }
118
- ```
119
-
120
- `basis: 'viewport'` percentages are relative to the scroll position they were
121
- measured at, which is why the hunt never scrolls between measuring and drawing.
122
- `basis: 'document'` is absolute. Both paths are covered by the alignment suite
123
- and land on the same pixels the selector path does.
124
-
125
- ## The reasoning step
126
-
127
- Point it at a URL. That's the whole invocation:
128
-
129
- ```bash
130
- npm run find-bugs -- --url https://news.ycombinator.com
131
- ```
132
-
133
- A ticket is optional. With one, findings are judged against it. Without one, the
134
- page is judged on its own terms.
135
-
136
- ```bash
137
- npm run find-bugs -- --url https://your.app/checkout \
138
- --ticket "CHK-482: customer reviews the order and places it"
139
- ```
140
-
141
- **The problem this solves.** A model cannot reliably invent a CSS selector by
142
- looking at a screenshot. So it is never asked to. Before the screenshot is taken,
143
- every candidate element is tagged with a `data-annot-ref` attribute and listed
144
- for the model with its tag, accessible name and bounding box:
145
-
146
- ```
147
- [e17] <button> "Apply" @ 1090,642 87x39 — #promo-apply
148
- [e24] <span> "£244.99" @ 1262,1046 57x22 — #grand-total-value
149
- ```
150
-
151
- The model returns a handle, which maps back to a selector guaranteed to resolve
152
- because we injected it. The readable selector (`#promo-apply`) still goes in the
153
- ticket. Those bounding boxes are also the model's best evidence for geometric
154
- bugs, since overlapping boxes and boxes that run past a parent show up in the
155
- numbers as clearly as in the pixels.
156
-
157
- **Structured output.** Findings come back through a strict tool schema:
158
-
159
- ```json
160
- { "description": "...", "evidence": "...", "severity": "blocker", "ref": "e17", "region": null }
161
- ```
162
-
163
- Severity drives the annotation colour. Every finding gets a cropped, dimmed
164
- close-up, and each pass also produces an overview with numbered markers, because
165
- full-sentence labels on an overview cover the rest of the page.
166
-
167
- **Three resolution paths, all tested:** a valid handle resolves to its injected
168
- selector; a handle the model invented falls back to the region it supplied; a
169
- finding with neither is reported as unresolved rather than silently dropped.
170
-
171
- **Viewport sweep.** `runBugHunt` works down the page one viewport at a time,
172
- overlapping passes by 10%. A pass is the unit of correctness: the inventory, the
173
- screenshot the model reasons over, and any percentage region it returns all share
174
- one scroll position. Findings are de-duplicated across passes by readable
175
- selector, since handles are re-issued each pass.
176
-
177
- ## Using this from a live agent session
178
-
179
- When Claude is already driving a real browser, say a Playwright MCP or Chrome
180
- DevTools MCP session that is logged in, the thing to avoid is opening a second
181
- one. A second browser would not share the session and would land on the SSO login
182
- page, so this path never opens one.
183
-
184
- Three pieces:
185
-
186
- - **[src/browser/measure-target.js](../src/browser/measure-target.js)** is a
187
- snippet to paste into whichever `evaluate` tool is live. Edit one line, run it,
188
- get `{ metrics, targets }` back. Both backends can write the result straight to
189
- a file (`filename` on Playwright MCP, `filePath` on Chrome DevTools MCP).
190
- - **`npm run annotate-shot`** takes a PNG plus that JSON and draws the boxes. It
191
- never opens a browser and knows nothing about either backend.
192
- - **[skills/annotate-bug/SKILL.md](../skills/annotate-bug/SKILL.md)** is the
193
- protocol written as a skill, with the exact tool calls for both backends. Copy
194
- it into `.claude/skills/`.
195
-
196
- ```bash
197
- npm run annotate-shot -- --image shot.png --measurement measure.json \
198
- --label "Apply button escapes its card" --out annotated.png --crop
199
- ```
200
-
201
- **The ordering rule that makes it work:** measure, then screenshot, with no
202
- navigation, scroll, or click in between. A rectangle is only valid for the scroll
203
- position it was measured at. Everything else the pipeline can recover from. This
204
- it cannot.
205
-
206
- **The scale is measured on every capture.** Both backends can hand back a resized
207
- image, Playwright MCP via `scale: "css"` and Chrome DevTools MCP via
208
- `--screenshot-max-width`, so `devicePixelRatio` describes the browser and says
209
- nothing about the file on disk. `resolveScale()` compares the image against the
210
- viewport it was supposed to cover, uses the measured ratio when the two disagree,
211
- and prints a warning. `npm run verify:image` proves this holds at scales from 0.5
212
- to 2.0, including a case downscaled to 900px from a 2560px capture.
213
-
214
- If there is no element to point at (blank space where something should render),
215
- `--region x,y,w,h` takes percentages of the viewport instead.
216
-
217
- ## How the reasoning step is verified
218
-
219
- The live call has been run against the real API (see below). It is also tested
220
- without credentials, so the suite stays runnable and free. `npm run test:reasoner`
221
- drives `ClaudeReasoner` through a stubbed `fetch` that returns a real SSE stream,
222
- covering request construction (model, strict tool schema, adaptive thinking, the
223
- image and inventory blocks), stream handling, tool-use parsing, all three
224
- resolution paths, refusals, and malformed model output. 12 checks.
225
-
226
- `npm run demo` then runs the whole pipeline against
227
- [fixtures/buggy-checkout.html](../fixtures/buggy-checkout.html), a page with five
228
- deliberate bugs, using recorded findings in place of the model. The recorded
229
- findings name real CSS selectors, which the replay translates into the handles
230
- the model would have returned, so the resolution path under test is identical to
231
- the live one. Two of the seven entries are deliberate fallback tests.
232
-
233
- **To run it live**, copy `.env.example` to `.env` and put your key in it:
234
-
235
- ```bash
236
- cp .env.example .env
237
- # ANTHROPIC_API_KEY=sk-ant-...
238
-
239
- npm run find-bugs -- --url https://your.app/checkout --ticket "CHK-482: ..."
240
- ```
241
-
242
- `.env` is read by `scripts/find-bugs.ts` via `process.loadEnvFile` and is
243
- gitignored. Exporting `ANTHROPIC_API_KEY` in your shell works too, as does an
244
- `ant auth login` profile, and the SDK resolves credentials in that order. It
245
- resolves them lazily, at request time rather than when the client is constructed,
246
- so a missing key surfaces on the first request. The CLI catches that and prints
247
- setup instructions instead of a stack trace.
248
-
249
- The library itself never reads `.env`. Only the CLI does, so importing
250
- `annotate()` or `ClaudeReasoner` into your own program leaves credential handling
251
- to you.
252
-
253
- ### What the first live runs showed
254
-
255
- On [fixtures/buggy-checkout.html](../fixtures/buggy-checkout.html) with **no
256
- ticket**, Claude found 4 of the 5 planted bugs, every selector resolved, and
257
- nothing was unresolved. It missed the `#place-order` button overlapping the terms
258
- text.
259
-
260
- The evidence it gave is the part that matters, because it shows the design
261
- premise holding up. It reasons from the bounding boxes as much as from the
262
- pixels:
263
-
264
- > `#postcode-field`: "e10/e11/e12 start at x=419 while all other fields (e3, e7,
265
- > e9, e13) start at x=385, and the input is narrower (476 vs 510)."
266
-
267
- Two real bugs surfaced from pointing it at Hacker News, both now fixed and
268
- covered by the alignment suite:
269
-
270
- - **Quirks mode.** HN has no doctype, so `documentElement.clientHeight` returns
271
- the *content* height (1214) instead of the viewport height (900). The sweep
272
- concluded the page fit on one screen, and percentage regions were measured
273
- against the wrong height. Metrics now use `window.innerWidth/innerHeight`, and
274
- [fixtures/quirks-page.html](../fixtures/quirks-page.html) covers it.
275
- - **Stale handles.** Each pass restarts its counter at `e1`, but the previous
276
- pass's attributes were still in the DOM, so `[data-annot-ref="e5"]` could match
277
- two elements and annotate the wrong one. The collector now clears stale handles
278
- before tagging.
279
-
280
- Both surfaced from the pipeline reporting its own warnings, which is the argument
281
- for keeping `warnings` in the report.
282
-
283
- ## Known limits
284
-
285
- - Findings vary between runs on the same page, as you'd expect. Two runs of the
286
- Hacker News front page returned three findings and one.
287
- - Judgement is not calibrated. The missing-domain finding on Hacker News is
288
- arguably a false positive, since HN legitimately shows no domain for text
289
- posts. The model considered that and reported it anyway.
290
- - `element` mode captures full-page and then crops, which is wasteful on very
291
- long pages. Fine at this stage, worth revisiting if it becomes a bottleneck.
292
- - The inventory covers the main document and same-origin iframes. Cross-origin
293
- frames are skipped, so bugs inside them will not be found.
294
- - Overview labels can still overlap each other when findings are close together.
295
-
296
- ## What's next here
297
-
298
- Selector accuracy looks like the solved part. Across the live runs so far, every
299
- handle Claude picked resolved to the element it described, and no real page has
300
- needed the region fallback yet.
301
-
302
- The open question has shifted to **judgement**, meaning precision and recall.
303
- Claude missed the button and text overlap on the fixture, and its Hacker News
304
- finding is arguably a false positive. Worth running against pages with known
305
- defects and counting both the misses and the false alarms. `report.json` already
306
- carries what that needs: `selector` is what Claude chose, `resolvedTo` is what
307
- got annotated, `warnings` flags ambiguity, and `unresolved` lists what it could
308
- not point at.
@@ -1,9 +0,0 @@
1
- import type { Page } from 'playwright';
2
- import type { Annotation, AnnotateOptions, AnnotateResult } from './types.js';
3
- /**
4
- * Playwright-driven annotation: position the page, measure, capture, and hand
5
- * the pixels to `annotateImage`, which owns all the coordinate maths and is
6
- * shared with the driver-agnostic path.
7
- */
8
- export declare function annotate(page: Page, annotations: Annotation[], options?: AnnotateOptions): Promise<AnnotateResult>;
9
- //# sourceMappingURL=annotate.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../src/annotate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AAE/F;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA+EzB"}
package/dist/annotate.js DELETED
@@ -1,82 +0,0 @@
1
- import { annotateImage } from './annotate-image.js';
2
- import { measureElement, measureRegion, readPageMetrics, scrollElementIntoView } from './measure.js';
3
- /**
4
- * Playwright-driven annotation: position the page, measure, capture, and hand
5
- * the pixels to `annotateImage`, which owns all the coordinate maths and is
6
- * shared with the driver-agnostic path.
7
- */
8
- export async function annotate(page, annotations, options = {}) {
9
- if (annotations.length === 0)
10
- throw new Error('No annotations supplied.');
11
- const mode = options.mode ?? 'viewport';
12
- const fullPageCapture = mode !== 'viewport';
13
- const warnings = [];
14
- // Positioning happens before measurement: any scroll invalidates every rect.
15
- if (fullPageCapture && (options.scrollToTop ?? true)) {
16
- await page.evaluate(() => window.scrollTo(0, 0));
17
- }
18
- else if (mode === 'viewport' && (options.scrollIntoView ?? true)) {
19
- // A region is defined relative to wherever the page already is, so
20
- // scrolling to reveal it would invalidate the very percentages given.
21
- const first = annotations[0];
22
- if (first?.selector)
23
- await scrollElementIntoView(page, first.selector);
24
- }
25
- await page.waitForTimeout(60);
26
- const metrics = await readPageMetrics(page);
27
- const elements = [];
28
- for (const annotation of annotations) {
29
- if (annotation.selector && annotation.region) {
30
- throw new Error('An annotation takes either a selector or a region, not both.');
31
- }
32
- if (annotation.selector) {
33
- elements.push(await measureElement(page, annotation.selector, metrics));
34
- }
35
- else if (annotation.region) {
36
- elements.push(measureRegion(annotation.region, metrics));
37
- }
38
- else {
39
- throw new Error('An annotation needs either a selector or a region.');
40
- }
41
- }
42
- for (const element of elements) {
43
- if (element.matchCount > 1) {
44
- warnings.push(`Selector "${element.selector}" matched ${element.matchCount} elements; annotated the first.`);
45
- }
46
- if (mode === 'viewport' && !element.inViewport) {
47
- warnings.push(`Element "${element.selector}" is outside the viewport; its box will be clipped.`);
48
- }
49
- }
50
- const screenshot = await page.screenshot({
51
- fullPage: fullPageCapture,
52
- animations: 'disabled',
53
- caret: 'hide',
54
- type: 'png',
55
- });
56
- const targets = elements.map((element, i) => ({
57
- viewportRect: element.viewportRect,
58
- documentRect: element.documentRect,
59
- isFixed: element.isFixed,
60
- label: annotations[i]?.label,
61
- shape: annotations[i]?.shape,
62
- style: annotations[i]?.style,
63
- describe: `Element "${element.selector}"`,
64
- }));
65
- const result = await annotateImage(screenshot, targets, {
66
- metrics,
67
- capture: fullPageCapture ? 'fullPage' : 'viewport',
68
- crop: mode === 'element',
69
- cropPadding: options.cropPadding,
70
- style: options.style,
71
- });
72
- return {
73
- image: result.image,
74
- rawImage: result.rawImage,
75
- width: result.width,
76
- height: result.height,
77
- metrics,
78
- elements,
79
- drawnRects: result.drawnRects,
80
- warnings: [...warnings, ...result.warnings],
81
- };
82
- }
@@ -1,158 +0,0 @@
1
- // This file is read as text and evaluated inside the page - it is never
2
- // imported or bundled. Keeping it out of the TypeScript build is deliberate:
3
- // esbuild's keepNames transform injects a `__name` helper into any function it
4
- // compiles, and that helper does not exist in the browser, so a serialized
5
- // TypeScript function throws `__name is not defined` on evaluation.
6
- //
7
- // The whole file is therefore a single arrow-function expression.
8
- //
9
- // Tags every candidate element with a ref attribute and returns a description
10
- // of it. Tagging rather than deriving a selector afterwards is deliberate: a
11
- // selector we injected always resolves, whereas a path built from classes can
12
- // be invalidated by anything that re-renders between measuring and annotating.
13
-
14
- (function (options) {
15
- var prefix = options.prefix;
16
- var refAttr = options.refAttr;
17
- var minSize = options.minSize;
18
- var viewportOnly = options.viewportOnly;
19
-
20
- var INTERACTIVE = ['a', 'button', 'input', 'select', 'textarea', 'label', 'summary', 'option'];
21
- var STRUCTURAL = ['header', 'nav', 'main', 'footer', 'aside', 'form', 'table', 'img', 'svg', 'video', 'dialog'];
22
- var HEADING = /^h[1-6]$/;
23
- var testAttrs = ['data-testid', 'data-test-id', 'data-test', 'data-cy', 'data-qa'];
24
-
25
- function readableSelector(el) {
26
- // Prefer whatever a developer would actually paste into devtools.
27
- var id = el.getAttribute('id');
28
- if (id && /^[A-Za-z][\w-]*$/.test(id) && el.ownerDocument.querySelectorAll('#' + id).length === 1) {
29
- return '#' + id;
30
- }
31
-
32
- for (var i = 0; i < testAttrs.length; i++) {
33
- var value = el.getAttribute(testAttrs[i]);
34
- if (value) {
35
- var candidate = '[' + testAttrs[i] + '="' + value + '"]';
36
- if (el.ownerDocument.querySelectorAll(candidate).length === 1) return candidate;
37
- }
38
- }
39
-
40
- var parts = [];
41
- var node = el;
42
- for (var depth = 0; node && depth < 4; depth++) {
43
- var tag = node.tagName.toLowerCase();
44
- if (tag === 'body' || tag === 'html') break;
45
-
46
- var nodeId = node.getAttribute('id');
47
- if (nodeId && /^[A-Za-z][\w-]*$/.test(nodeId)) {
48
- parts.unshift('#' + nodeId);
49
- break;
50
- }
51
-
52
- var parent = node.parentElement;
53
- var part = tag;
54
- if (parent) {
55
- var siblings = [];
56
- for (var c = 0; c < parent.children.length; c++) {
57
- if (parent.children[c].tagName === node.tagName) siblings.push(parent.children[c]);
58
- }
59
- if (siblings.length > 1) part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')';
60
- }
61
- parts.unshift(part);
62
-
63
- var joined = parts.join(' > ');
64
- try {
65
- if (el.ownerDocument.querySelectorAll(joined).length === 1) return joined;
66
- } catch (e) {
67
- // An unusual tag name can produce an invalid selector; keep walking.
68
- }
69
- node = parent;
70
- }
71
- return parts.join(' > ') || el.tagName.toLowerCase();
72
- }
73
-
74
- function accessibleName(el) {
75
- var aria = el.getAttribute('aria-label');
76
- if (aria) return aria.trim();
77
- var alt = el.getAttribute('alt');
78
- if (alt) return alt.trim();
79
- var placeholder = el.getAttribute('placeholder');
80
- if (placeholder) return 'placeholder: ' + placeholder.trim();
81
- if (el.tagName === 'INPUT' && typeof el.value === 'string' && el.value) {
82
- return 'value: ' + el.value.trim();
83
- }
84
- return (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80);
85
- }
86
-
87
- // An element a developer deliberately named is worth listing even when it is
88
- // just a wrapper - a misaligned or overflowing container is exactly the kind
89
- // of target whose children, not itself, carry the text.
90
- function hasStableName(el) {
91
- if (el.hasAttribute('id')) return true;
92
- for (var i = 0; i < testAttrs.length; i++) {
93
- if (el.hasAttribute(testAttrs[i])) return true;
94
- }
95
- return false;
96
- }
97
-
98
- // Text-bearing leaf: has its own text but no child element that also has text.
99
- function isTextLeaf(el) {
100
- if (!(el.textContent || '').trim()) return false;
101
- for (var i = 0; i < el.children.length; i++) {
102
- if ((el.children[i].textContent || '').trim()) return false;
103
- }
104
- return true;
105
- }
106
-
107
- // Clear handles left by an earlier pass. Counters restart at 1 each time, so
108
- // without this a stale e5 from a previous scroll position still matches
109
- // [data-annot-ref="e5"] and the annotation can land on the wrong element.
110
- var stale = document.querySelectorAll('[' + refAttr + ']');
111
- for (var s = 0; s < stale.length; s++) stale[s].removeAttribute(refAttr);
112
-
113
- var results = [];
114
- var counter = 0;
115
- var all = document.querySelectorAll('*');
116
-
117
- for (var i = 0; i < all.length; i++) {
118
- var el = all[i];
119
- var tag = el.tagName.toLowerCase();
120
- if (tag === 'script' || tag === 'style' || tag === 'meta' || tag === 'link') continue;
121
-
122
- var style = getComputedStyle(el);
123
- if (style.visibility === 'hidden' || style.display === 'none') continue;
124
- if (parseFloat(style.opacity) < 0.05) continue;
125
-
126
- var rect = el.getBoundingClientRect();
127
- if (rect.width < minSize || rect.height < minSize) continue;
128
-
129
- var intersects =
130
- rect.bottom > 0 && rect.right > 0 &&
131
- rect.top < window.innerHeight && rect.left < window.innerWidth;
132
- if (viewportOnly && !intersects) continue;
133
-
134
- var interesting =
135
- INTERACTIVE.indexOf(tag) !== -1 ||
136
- STRUCTURAL.indexOf(tag) !== -1 ||
137
- HEADING.test(tag) ||
138
- el.hasAttribute('role') ||
139
- hasStableName(el) ||
140
- isTextLeaf(el);
141
- if (!interesting) continue;
142
-
143
- var ref = prefix + ++counter;
144
- el.setAttribute(refAttr, ref);
145
-
146
- results.push({
147
- ref: ref,
148
- reportSelector: readableSelector(el),
149
- tag: tag,
150
- role: el.getAttribute('role'),
151
- name: accessibleName(el),
152
- rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
153
- inViewport: intersects,
154
- });
155
- }
156
-
157
- return results;
158
- })
@@ -1,69 +0,0 @@
1
- // Paste this into whichever browser MCP is live, as the evaluate function:
2
- //
3
- // Playwright MCP browser_evaluate({ function: "<this>", filename: "measure.json" })
4
- // Chrome DevTools evaluate_script({ pageId, function: "<this>", filePath: "measure.json" })
5
- //
6
- // Edit the SELECTORS line, and nothing else. The result is the exact JSON that
7
- // `annotate-shot --measurement` expects.
8
- //
9
- // It deliberately does not scroll, click, or change anything: every rectangle it
10
- // returns is only valid for the scroll position the page is in right now, so
11
- // the screenshot must be taken immediately after this runs, with no navigation
12
- // in between.
13
-
14
- () => {
15
- const SELECTORS = ['#place-order'];
16
-
17
- const doc = document.documentElement;
18
- const body = document.body;
19
-
20
- const metrics = {
21
- devicePixelRatio: window.devicePixelRatio,
22
- scrollX: window.scrollX,
23
- scrollY: window.scrollY,
24
- // innerWidth/Height rather than documentElement.clientWidth/Height: on a
25
- // page with no doctype (quirks mode) the root element reports the content
26
- // size, not the viewport.
27
- viewportWidth: window.innerWidth,
28
- viewportHeight: window.innerHeight,
29
- documentWidth: Math.max(doc.scrollWidth, body ? body.scrollWidth : 0),
30
- documentHeight: Math.max(doc.scrollHeight, body ? body.scrollHeight : 0),
31
- };
32
-
33
- const targets = SELECTORS.map((selector) => {
34
- let matches;
35
- try {
36
- matches = document.querySelectorAll(selector);
37
- } catch (e) {
38
- return { selector, found: false, error: 'invalid selector: ' + e.message };
39
- }
40
- if (matches.length === 0) return { selector, found: false, error: 'no element matched' };
41
-
42
- const el = matches[0];
43
- const r = el.getBoundingClientRect();
44
-
45
- // An element inside a fixed subtree does not move with document scroll, so
46
- // it has no meaningful document-space position.
47
- let isFixed = false;
48
- for (let node = el; node; node = node.parentElement) {
49
- if (getComputedStyle(node).position === 'fixed') {
50
- isFixed = true;
51
- break;
52
- }
53
- }
54
-
55
- return {
56
- selector,
57
- found: true,
58
- matchCount: matches.length,
59
- tag: el.tagName.toLowerCase(),
60
- text: (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
61
- isFixed,
62
- rect: { x: r.x, y: r.y, width: r.width, height: r.height },
63
- inViewport:
64
- r.bottom > 0 && r.right > 0 && r.top < window.innerHeight && r.left < window.innerWidth,
65
- };
66
- });
67
-
68
- return { metrics, targets };
69
- }
@@ -1,17 +0,0 @@
1
- import Anthropic from '@anthropic-ai/sdk';
2
- import type { BugFinding, Reasoner, ReasonerInput } from './finder.js';
3
- export interface ClaudeReasonerOptions {
4
- model?: string;
5
- maxTokens?: number;
6
- effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
7
- client?: Anthropic;
8
- }
9
- export declare class ClaudeReasoner implements Reasoner {
10
- private readonly client;
11
- private readonly model;
12
- private readonly maxTokens;
13
- private readonly effort;
14
- constructor(options?: ClaudeReasonerOptions);
15
- propose(input: ReasonerInput): Promise<BugFinding[]>;
16
- }
17
- //# sourceMappingURL=claude-reasoner.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"claude-reasoner.d.ts","sourceRoot":"","sources":["../src/claude-reasoner.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AA2FjF,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACrD,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;gBAEzD,OAAO,GAAE,qBAA0B;IAOzC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;CAkE3D"}