@kaynooo/cli-page 0.0.0-stage → 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.
@@ -0,0 +1,159 @@
1
+ import type { Compared, CompareInput, Region } from '../src/types'
2
+
3
+ // Runs in a blank page: src/inpage.ts sends this file's transpiled source with a call to compareImages, so it may import types alone.
4
+
5
+ /** Compares two PNGs pixel by pixel and boxes the differing regions, cells of 8px joined across a 16px gap so a changed line of text makes one box. */
6
+ export async function compareImages({ mockup, built, threshold }: CompareInput): Promise<Compared> {
7
+ const cell = 8
8
+ const reach = 2
9
+ const gap = 24
10
+ const box = '#d0006f'
11
+
12
+ async function bitmap(base64: string): Promise<ImageBitmap> {
13
+ const response = await fetch(`data:image/png;base64,${base64}`)
14
+
15
+ return createImageBitmap(await response.blob())
16
+ }
17
+
18
+ function canvasOf(width: number, height: number): [HTMLCanvasElement, CanvasRenderingContext2D] {
19
+ const canvas = document.createElement('canvas')
20
+
21
+ canvas.width = width
22
+ canvas.height = height
23
+
24
+ return [canvas, canvas.getContext('2d')!]
25
+ }
26
+
27
+ const [left, right] = await Promise.all([bitmap(mockup), bitmap(built)])
28
+ const width = Math.max(left.width, right.width)
29
+ const height = Math.max(left.height, right.height)
30
+
31
+ function pixels(image: ImageBitmap): Uint8ClampedArray {
32
+ const [, context] = canvasOf(width, height)
33
+
34
+ context.fillStyle = '#fff'
35
+ context.fillRect(0, 0, width, height)
36
+ context.drawImage(image, 0, 0)
37
+
38
+ return context.getImageData(0, 0, width, height).data
39
+ }
40
+
41
+ const a = pixels(left)
42
+ const b = pixels(right)
43
+ const columns = Math.ceil(width / cell)
44
+ const rows = Math.ceil(height / cell)
45
+ const counts = new Uint32Array(columns * rows)
46
+ const mask = new Uint8Array(width * height)
47
+ let differing = 0
48
+
49
+ for (let y = 0; y < height; y++) {
50
+ for (let x = 0; x < width; x++) {
51
+ const at = (y * width + x) * 4
52
+ const distance = Math.max(Math.abs(a[at]! - b[at]!), Math.abs(a[at + 1]! - b[at + 1]!), Math.abs(a[at + 2]! - b[at + 2]!))
53
+
54
+ if (distance > threshold) {
55
+ mask[y * width + x] = 1
56
+ differing++
57
+ counts[Math.floor(y / cell) * columns + Math.floor(x / cell)]! += 1
58
+ }
59
+ }
60
+ }
61
+
62
+ // A cell with a lone differing pixel is antialiasing noise, not a change.
63
+ const dirty = (index: number): boolean => counts[index]! >= 2
64
+ const seen = new Uint8Array(columns * rows)
65
+ const regions: Region[] = []
66
+
67
+ for (let start = 0; start < counts.length; start++) {
68
+ if (seen[start] === 1 || !dirty(start))
69
+ continue
70
+
71
+ let minX = columns
72
+ let minY = rows
73
+ let maxX = 0
74
+ let maxY = 0
75
+ const queue = [start]
76
+
77
+ seen[start] = 1
78
+
79
+ for (const index of queue) {
80
+ const cx = index % columns
81
+ const cy = Math.floor(index / columns)
82
+
83
+ minX = Math.min(minX, cx)
84
+ maxX = Math.max(maxX, cx)
85
+ minY = Math.min(minY, cy)
86
+ maxY = Math.max(maxY, cy)
87
+
88
+ for (let dy = -reach; dy <= reach; dy++) {
89
+ for (let dx = -reach; dx <= reach; dx++) {
90
+ const nx = cx + dx
91
+ const ny = cy + dy
92
+ const next = ny * columns + nx
93
+
94
+ if (nx >= 0 && ny >= 0 && nx < columns && ny < rows && seen[next] === 0 && dirty(next)) {
95
+ seen[next] = 1
96
+ queue.push(next)
97
+ }
98
+ }
99
+ }
100
+ }
101
+
102
+ const x = minX * cell
103
+ const y = minY * cell
104
+
105
+ regions.push({ x, y, width: Math.min((maxX + 1) * cell, width) - x, height: Math.min((maxY + 1) * cell, height) - y })
106
+ }
107
+
108
+ regions.sort((one, two) => one.y - two.y || one.x - two.x)
109
+
110
+ function outline(context: CanvasRenderingContext2D, offset: number): void {
111
+ context.lineWidth = 2
112
+ context.font = 'bold 12px sans-serif'
113
+
114
+ for (const [index, region] of regions.entries()) {
115
+ const label = String(index + 1)
116
+ const labelWidth = context.measureText(label).width + 8
117
+
118
+ context.strokeStyle = box
119
+ context.strokeRect(offset + region.x + 1, region.y + 1, Math.max(region.width - 2, 1), Math.max(region.height - 2, 1))
120
+ context.fillStyle = box
121
+ context.fillRect(offset + region.x, Math.max(region.y - 16, 0), labelWidth, 16)
122
+ context.fillStyle = '#fff'
123
+ context.fillText(label, offset + region.x + 4, Math.max(region.y - 16, 0) + 12)
124
+ }
125
+ }
126
+
127
+ const [overlay, overlayContext] = canvasOf(width, height)
128
+ const faded = overlayContext.createImageData(width, height)
129
+
130
+ for (let index = 0; index < width * height; index++) {
131
+ const at = index * 4
132
+
133
+ if (mask[index] === 1) {
134
+ faded.data.set([230, 0, 60, 255], at)
135
+ }
136
+ else {
137
+ faded.data.set([b[at]! / 4 + 191, b[at + 1]! / 4 + 191, b[at + 2]! / 4 + 191, 255], at)
138
+ }
139
+ }
140
+
141
+ overlayContext.putImageData(faded, 0, 0)
142
+ outline(overlayContext, 0)
143
+
144
+ const [side, sideContext] = canvasOf(width * 2 + gap, height)
145
+
146
+ sideContext.fillStyle = '#888'
147
+ sideContext.fillRect(0, 0, width * 2 + gap, height)
148
+ sideContext.fillStyle = '#fff'
149
+ sideContext.fillRect(0, 0, width, height)
150
+ sideContext.fillRect(width + gap, 0, width, height)
151
+ sideContext.drawImage(left, 0, 0)
152
+ sideContext.drawImage(right, width + gap, 0)
153
+ outline(sideContext, 0)
154
+ outline(sideContext, width + gap)
155
+
156
+ const base64 = (canvas: HTMLCanvasElement): string => canvas.toDataURL('image/png').slice('data:image/png;base64,'.length)
157
+
158
+ return { width, mockupHeight: left.height, builtHeight: right.height, differing: differing / (width * height), regions, side: base64(side), overlay: base64(overlay) }
159
+ }
@@ -0,0 +1,336 @@
1
+ import type { DomFinding, FontSample } from '../src/types'
2
+
3
+ // Runs in the page: src/inpage.ts sends this file's transpiled source with a call to one of its exports, so it may import types alone.
4
+
5
+ const NUMBERS = /[\d.]+/g
6
+ const NOT_SPACE = /\S/
7
+
8
+ interface ShiftState {
9
+ score: number
10
+ node: Node | null
11
+ }
12
+
13
+ declare global {
14
+ var __pageShifts: ShiftState | undefined
15
+ }
16
+
17
+ /** Added before the page loads: keeps the cumulative layout shift score (its worst session window) and the node that moved most in it. */
18
+ export function watchShifts(): void {
19
+ const state: ShiftState = { score: 0, node: null }
20
+ let session = 0
21
+ let first = 0
22
+ let last = 0
23
+ let biggest = 0
24
+ let biggestNode: Node | null = null
25
+
26
+ globalThis.__pageShifts = state
27
+
28
+ try {
29
+ new PerformanceObserver((list) => {
30
+ for (const entry of list.getEntries() as (PerformanceEntry & { value: number, hadRecentInput: boolean, sources?: { node?: Node | null }[] })[]) {
31
+ if (entry.hadRecentInput)
32
+ continue
33
+
34
+ // A window closes after a second without a shift, or five seconds after it opened.
35
+ if (entry.startTime - last > 1000 || entry.startTime - first > 5000) {
36
+ session = 0
37
+ first = entry.startTime
38
+ biggest = 0
39
+ biggestNode = null
40
+ }
41
+
42
+ session += entry.value
43
+ last = entry.startTime
44
+
45
+ if (entry.value > biggest) {
46
+ biggest = entry.value
47
+ biggestNode = entry.sources?.find(source => source.node !== undefined && source.node !== null)?.node ?? null
48
+ }
49
+
50
+ if (session > state.score) {
51
+ state.score = session
52
+ state.node = biggestNode
53
+ }
54
+ }
55
+ }).observe({ type: 'layout-shift', buffered: true })
56
+ }
57
+ catch {}
58
+ }
59
+
60
+ function describe(element: Element): string {
61
+ const tag = element.tagName.toLowerCase()
62
+
63
+ if (element.id !== '')
64
+ return `${tag}#${element.id}`
65
+
66
+ const classes = [...element.classList].slice(0, 2)
67
+ const own = classes.length > 0 ? `${tag}.${classes.join('.')}` : tag
68
+ const parent = element.parentElement
69
+
70
+ if (classes.length > 0 || parent === null || parent === document.body || parent === document.documentElement || element === document.body)
71
+ return own
72
+
73
+ return `${describe(parent)} > ${own}`
74
+ }
75
+
76
+ function visible(element: Element): boolean {
77
+ const rect = element.getBoundingClientRect()
78
+ const style = getComputedStyle(element)
79
+
80
+ return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden' && style.opacity !== '0'
81
+ }
82
+
83
+ function alpha(color: string): number {
84
+ if (color === 'transparent')
85
+ return 0
86
+
87
+ const parts = color.match(NUMBERS) ?? []
88
+
89
+ return color.startsWith('rgba') || parts.length === 4 ? Number(parts[3] ?? 1) : 1
90
+ }
91
+
92
+ // The colour painted behind an element by its nearest ancestor with an opaque enough background.
93
+ function backdrop(element: Element | null): string {
94
+ for (let at = element; at !== null; at = at.parentElement) {
95
+ const color = getComputedStyle(at).backgroundColor
96
+
97
+ if (alpha(color) > 0)
98
+ return color
99
+ }
100
+
101
+ return 'rgb(255, 255, 255)'
102
+ }
103
+
104
+ // The sides on which the element draws an edge of its own: each side with a visible border, or all four for a background unlike what is behind it.
105
+ function edgesOf(element: Element): string[] {
106
+ const style = getComputedStyle(element)
107
+ const sides = ['top', 'right', 'bottom', 'left']
108
+
109
+ if (style.backgroundImage !== 'none' || (alpha(style.backgroundColor) > 0 && style.backgroundColor !== backdrop(element.parentElement)))
110
+ return sides
111
+
112
+ return sides.filter(side => Number.parseFloat(style.getPropertyValue(`border-${side}-width`)) > 0 && style.getPropertyValue(`border-${side}-style`) !== 'none' && alpha(style.getPropertyValue(`border-${side}-color`)) > 0)
113
+ }
114
+
115
+ /** Every DOM-measured defect at the current width; `phone` raises the smallest tap target from 24px to 44px. */
116
+ export function measureDom(phone: boolean): DomFinding[] {
117
+ const findings: DomFinding[] = []
118
+ const root = document.scrollingElement ?? document.documentElement
119
+ const viewport = root.clientWidth
120
+ const px = (value: number): string => `${Math.round(value)}px`
121
+
122
+ // Overflow: the page scrolls sideways; name the elements where it starts, not every descendant riding along.
123
+ const by = root.scrollWidth - viewport
124
+
125
+ if (by > 0) {
126
+ const escapes = (element: Element): boolean => {
127
+ for (let at: Element | null = element; at !== null && at !== document.body; at = at.parentElement) {
128
+ const style = getComputedStyle(at)
129
+
130
+ if (style.position === 'fixed')
131
+ return false
132
+
133
+ if (at !== element && style.overflowX !== 'visible')
134
+ return false
135
+ }
136
+
137
+ return true
138
+ }
139
+ const culprits = [...document.body.querySelectorAll('*')]
140
+ .filter((element) => {
141
+ const right = element.getBoundingClientRect().right
142
+ const parent = element.parentElement
143
+
144
+ return right > viewport + 0.5 && escapes(element) && (parent === null || parent === document.body || parent.getBoundingClientRect().right <= viewport + 0.5)
145
+ })
146
+ .toSorted((a, b) => b.getBoundingClientRect().right - a.getBoundingClientRect().right)
147
+ .slice(0, 3)
148
+
149
+ for (const element of culprits) {
150
+ const right = element.getBoundingClientRect().right
151
+
152
+ findings.push({ kind: 'overflow', selector: describe(element), message: `right edge at ${px(right)}, ${px(right - viewport)} past the ${px(viewport)} viewport` })
153
+ }
154
+
155
+ if (culprits.length === 0)
156
+ findings.push({ kind: 'overflow', selector: 'html', message: `the page scrolls ${px(by)} sideways` })
157
+ }
158
+
159
+ // Tap targets: a control smaller than a finger at phone widths, or than WCAG 2.5.8's 24px elsewhere; a link inside a sentence is exempt.
160
+ const least = phone ? 44 : 24
161
+ const controls = document.querySelectorAll('a[href], button, input:not([type="hidden"]), select, textarea, summary, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="menuitem"]')
162
+
163
+ for (const control of controls) {
164
+ if (!visible(control) || (control as HTMLButtonElement).disabled)
165
+ continue
166
+
167
+ let rect = control.getBoundingClientRect()
168
+
169
+ // Visually hidden helpers such as skip links are 1px squares until focused.
170
+ if (rect.width <= 1 || rect.height <= 1)
171
+ continue
172
+
173
+ const style = getComputedStyle(control)
174
+ const parent = control.parentElement
175
+
176
+ if (style.display === 'inline' && parent !== null && (parent.textContent ?? '').trim().length > (control.textContent ?? '').trim().length)
177
+ continue
178
+
179
+ // A checkbox or radio is hit through its label too.
180
+ const labels = (control as HTMLInputElement).labels
181
+
182
+ if (labels !== null && labels !== undefined) {
183
+ for (const label of labels) {
184
+ const area = label.getBoundingClientRect()
185
+
186
+ if (area.width * area.height > rect.width * rect.height)
187
+ rect = area
188
+ }
189
+ }
190
+
191
+ if (rect.width < least || rect.height < least)
192
+ findings.push({ kind: 'tap-target', selector: describe(control), message: `${Math.round(rect.width)}×${Math.round(rect.height)}px, under ${least}px` })
193
+ }
194
+
195
+ // Padding: text flush against the border or background edge of the box drawing it.
196
+ const touched = new Map<Element, Set<string>>()
197
+ const range = document.createRange()
198
+
199
+ for (const element of document.body.querySelectorAll('*')) {
200
+ const texts = [...element.childNodes].filter(node => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '')
201
+
202
+ if (texts.length === 0 || !visible(element) || ['MARK', 'SCRIPT', 'STYLE', 'NOSCRIPT'].includes(element.tagName))
203
+ continue
204
+
205
+ let box: Element | null = element
206
+ let edges: string[] = []
207
+
208
+ for (; box !== null && box !== document.body; box = box.parentElement) {
209
+ edges = edgesOf(box)
210
+
211
+ if (edges.length > 0)
212
+ break
213
+ }
214
+
215
+ if (box === null || box === document.body)
216
+ continue
217
+
218
+ let left = Infinity
219
+ let right = -Infinity
220
+ let top = Infinity
221
+ let bottom = -Infinity
222
+
223
+ for (const node of texts) {
224
+ const content = node.textContent ?? ''
225
+
226
+ range.setStart(node, content.search(NOT_SPACE))
227
+ range.setEnd(node, content.trimEnd().length)
228
+
229
+ for (const rect of range.getClientRects()) {
230
+ left = Math.min(left, rect.left)
231
+ right = Math.max(right, rect.right)
232
+ top = Math.min(top, rect.top)
233
+ bottom = Math.max(bottom, rect.bottom)
234
+ }
235
+ }
236
+
237
+ if (left === Infinity)
238
+ continue
239
+
240
+ const outer = box.getBoundingClientRect()
241
+ const style = getComputedStyle(box)
242
+ const border = (side: string): number => Number.parseFloat(style.getPropertyValue(`border-${side}-width`)) || 0
243
+ const gaps: Record<string, number> = { top: top - outer.top - border('top'), right: outer.right - border('right') - right, bottom: outer.bottom - border('bottom') - bottom, left: left - outer.left - border('left') }
244
+
245
+ for (const side of edges) {
246
+ // An inline box is exactly as tall as its text, so only its sides can lack padding.
247
+ if (style.display === 'inline' && (side === 'top' || side === 'bottom'))
248
+ continue
249
+
250
+ if (Math.abs(gaps[side] ?? Infinity) < 1) {
251
+ const sides = touched.get(box) ?? new Set<string>()
252
+
253
+ sides.add(side)
254
+ touched.set(box, sides)
255
+ }
256
+ }
257
+ }
258
+
259
+ for (const [box, sides] of touched) {
260
+ const order = ['top', 'right', 'bottom', 'left'].filter(side => sides.has(side))
261
+ const named = order.length === 1 ? order[0] : `${order.slice(0, -1).join(', ')} and ${order.at(-1)}`
262
+
263
+ findings.push({ kind: 'padding', selector: describe(box), message: `text touches its ${named} edge, no padding` })
264
+ }
265
+
266
+ // Images that finished loading with nothing to draw.
267
+ for (const image of document.images) {
268
+ const source = image.currentSrc || image.src
269
+
270
+ if (source !== '' && image.complete && image.naturalWidth === 0)
271
+ findings.push({ kind: 'image', selector: describe(image), message: `${source.length > 120 ? `${source.slice(0, 117)}...` : source} did not load` })
272
+ }
273
+
274
+ const shifts = globalThis.__pageShifts
275
+
276
+ if (shifts !== undefined && shifts.score > 0.1) {
277
+ const node = shifts.node
278
+ const element = node instanceof Element ? node : node?.parentElement ?? null
279
+
280
+ findings.push({ kind: 'layout-shift', selector: element === null ? 'html' : describe(element), message: `layout shift score ${shifts.score.toFixed(2)}, over 0.1` })
281
+ }
282
+
283
+ return findings
284
+ }
285
+
286
+ // Marks a few elements per family, weight and style holding text of their own, so CDP can find them by selector.
287
+ export function markFontSamples({ mark, perStyle, max }: { mark: string, perStyle: number, max: number }): FontSample[] {
288
+ const counts = new Map<string, number>()
289
+ const samples: FontSample[] = []
290
+
291
+ for (const element of document.body.querySelectorAll('*')) {
292
+ if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(element.tagName))
293
+ continue
294
+
295
+ const hasText = [...element.childNodes].some(node => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '')
296
+ const rect = element.getBoundingClientRect()
297
+
298
+ if (!hasText || rect.width === 0 || rect.height === 0)
299
+ continue
300
+
301
+ const style = getComputedStyle(element)
302
+ const key = `${style.fontFamily}|${style.fontWeight}|${style.fontStyle}`
303
+ const count = (counts.get(key) ?? 0) + 1
304
+
305
+ counts.set(key, count)
306
+
307
+ if (count <= perStyle && samples.length < max) {
308
+ element.setAttribute(mark, String(samples.length))
309
+ samples.push({ index: samples.length, stack: style.fontFamily, selector: describe(element), style: key, count: 0 })
310
+ }
311
+ }
312
+
313
+ return samples.map(sample => ({ ...sample, count: counts.get(sample.style) ?? 1 }))
314
+ }
315
+
316
+ // Whether the browser draws `family` with every glyph the same width.
317
+ export function monospaced(family: string): boolean {
318
+ const context = document.createElement('canvas').getContext('2d')
319
+
320
+ if (context === null)
321
+ return false
322
+
323
+ context.font = `32px "${family}"`
324
+
325
+ return Math.abs(context.measureText('iiiiii').width - context.measureText('MMMMMM').width) < 0.5
326
+ }
327
+
328
+ export async function fontsReady(): Promise<void> {
329
+ await document.fonts.ready
330
+ }
331
+
332
+ // Takes off the marks markFontSamples left once CDP has read them.
333
+ export function unmarkFontSamples(mark: string): void {
334
+ for (const element of document.querySelectorAll(`[${mark}]`))
335
+ element.removeAttribute(mark)
336
+ }
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@kaynooo/cli-page",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "type": "module",
4
+ "version": "0.0.2",
5
+ "description": "page: shoots HTML files or URLs at several widths in a local Chromium and reports their layout defects one line each, or diffs a built page against its mockup.",
6
+ "author": "Kaynooo <contact@kaynooo.fr>",
7
+ "license": "MIT",
8
+ "homepage": "https://github.com/Kayno0o/cli/tree/main/packages/page#readme",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/Kayno0o/cli.git",
12
+ "directory": "packages/page"
13
+ },
14
+ "bugs": "https://github.com/Kayno0o/cli/issues",
15
+ "keywords": [
16
+ "cli",
17
+ "screenshot",
18
+ "layout",
19
+ "chromium",
20
+ "playwright",
21
+ "mockup"
22
+ ],
23
+ "bin": {
24
+ "page": "./dist/cli.js"
25
+ },
26
+ "files": [
27
+ "dist",
28
+ "inpage/*.ts"
29
+ ],
30
+ "engines": {
31
+ "bun": ">=1.4.3"
32
+ },
33
+ "publishConfig": {
34
+ "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
35
+ },
36
+ "scripts": {
37
+ "build": "$npm_execpath build src/cli.ts --target bun --outdir dist --external playwright-core",
38
+ "page": "$npm_execpath src/cli.ts"
39
+ },
40
+ "dependencies": {
41
+ "playwright-core": "1.64.1"
42
+ },
43
+ "devDependencies": {
44
+ "@kaynooo/cli-kit": "0.46.4"
45
+ }
46
+ }