oh-my-opencode 5.1.51 → 5.1.55

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/support/padding.ts

@@ -0,0 +1,93 @@
+import { ancestors, childrenOf, descendants, fontSizePx, parentOf, styleOf } from "../../../core/page"
+import { parseColor } from "../../../core/color"
+import type { ElementSnapshot, PageSnapshot, Rect } from "../../../types"
+import { fillDiffers } from "./cards"
+import { alpha, bottom, chain, clipsX, clipsY, length, lineHeight, painted, right } from "./geometry"
+
+const same = (a: string, b: string): boolean => {
+	const x = parseColor(a)
+	const y = parseColor(b)
+	return x !== null && y !== null && Math.max(Math.abs(x.r - y.r), Math.abs(x.g - y.g), Math.abs(x.b - y.b), Math.abs(x.a - y.a) * 255) < 8
+}
+
+export function paddingFill(s: PageSnapshot, el: ElementSnapshot): boolean {
+	if (alpha(el, "background-color") === 0 || !fillDiffers(s, el)) return false
+	const fill = styleOf(el, "background-color")
+	for (const p of ancestors(s, el)) {
+		const image = styleOf(p, "background-image")
+		const lead = /^linear-gradient\(to (right|left|bottom|top), rgba\(0, 0, 0, 0\) ([\d.]+)(px|%), (rgba?\([^)]*\)) ([\d.]+)(px|%)\)$/.exec(image)
+		if (lead && same(fill, lead[4] ?? "") && lead[2] === lead[5] && lead[3] === lead[6]) {
+			const vertical = lead[1] === "top" || lead[1] === "bottom"
+			const span = vertical ? p.rect.height : p.rect.width
+			const stop = Number(lead[2]) * (lead[3] === "%" ? span / 100 : 1)
+			if (lead[1] === "right" && el.rect.x >= p.rect.x + stop - 0.5 ||
+				lead[1] === "left" && right(el.rect) <= right(p.rect) - stop + 0.5 ||
+				lead[1] === "bottom" && el.rect.y >= p.rect.y + stop - 0.5 ||
+				lead[1] === "top" && bottom(el.rect) <= bottom(p.rect) - stop + 0.5) return false
+		}
+		if (alpha(p, "background-color") > 0) break
+	}
+	return true
+}
+
+export function paddingBackdrop(s: PageSnapshot, el: ElementSnapshot): boolean {
+	for (const node of chain(s, el).slice(0, 12)) {
+		const p = parentOf(s, node)
+		if (!p) break
+		for (const sibling of childrenOf(s, p).slice(0, childrenOf(s, p).indexOf(node)).reverse()) {
+			const r = sibling.rect
+			if (styleOf(sibling, "display") === "none" || r.x > el.rect.x + 1 || r.y > el.rect.y + 1 ||
+				right(r) < right(el.rect) - 1 || bottom(r) < bottom(el.rect) - 1) continue
+			if (alpha(sibling, "background-color") > 0) return same(styleOf(el, "background-color"), styleOf(sibling, "background-color"))
+			if ([sibling, ...descendants(s, sibling)].some((n) => /^(img|video)$/.test(n.tag) && painted(s, n) &&
+				n.rect.x <= el.rect.x + 1 && n.rect.y <= el.rect.y + 1 && right(n.rect) >= right(el.rect) - 1 && bottom(n.rect) >= bottom(el.rect) - 1)) return true
+		}
+		if (alpha(p, "background-color") > 0) break
+	}
+	return false
+}
+
+export function continuedFill(s: PageSnapshot, el: ElementSnapshot, side: number): boolean {
+	const r = el.rect
+	const reaches = (b: Rect): boolean => Math.abs([bottom(b) - r.y, b.x - right(r), b.y - bottom(r), right(b) - r.x][side] ?? Infinity) <= 1.5
+	const along = (b: Rect): boolean => side % 2 === 0
+		? Math.min(right(r), right(b)) - Math.max(r.x, b.x) >= r.width * 0.9
+		: Math.min(bottom(r), bottom(b)) - Math.max(r.y, b.y) >= r.height * 0.9
+	const search = (node: ElementSnapshot, depth: number): boolean => {
+		if (!reaches(node.rect) || !painted(s, node)) return false
+		if (along(node.rect) && same(styleOf(el, "background-color"), styleOf(node, "background-color"))) return true
+		return depth < 6 && childrenOf(s, node).some((n) => search(n, depth + 1))
+	}
+	for (const node of chain(s, el).slice(0, 5)) {
+		const p = parentOf(s, node)
+		if (p && childrenOf(s, p).some((n) => n !== node && search(n, 0))) return true
+	}
+	return false
+}
+
+export function glyphBand(el: ElementSnapshot, r: Rect, scale = 1): Rect {
+	const size = fontSizePx(el) * scale
+	const pitch = lineHeight(el) * scale
+	const count = Math.max(1, Math.round((r.height - size) / pitch) + 1)
+	const inset = Math.max(0, (r.height - (count - 1) * pitch - size) / 2)
+	return { ...r, y: r.y + inset, height: r.height - inset * 2 }
+}
+
+export const paddingScale = (el: ElementSnapshot): number => {
+	const layout = el.scroll.clientWidth + length(el, "border-left-width") + length(el, "border-right-width")
+	const scale = el.rect.width / layout
+	return scale > 0.05 && scale < 0.95 ? scale : 1
+}
+
+export function uncut(s: PageSnapshot, node: ElementSnapshot, wrapper: ElementSnapshot, r: Rect, side: number): boolean {
+	for (const p of chain(s, node)) {
+		if (styleOf(p, "display") !== "inline") {
+			if (side === 1 && clipsX(p) && right(r) > right(p.rect) - length(p, "border-right-width") + 0.5 ||
+				side === 3 && clipsX(p) && r.x < p.rect.x + length(p, "border-left-width") - 0.5 ||
+				side === 0 && clipsY(p) && r.y < p.rect.y + length(p, "border-top-width") - 0.5 ||
+				side === 2 && clipsY(p) && bottom(r) > bottom(p.rect) - length(p, "border-bottom-width") + 0.5) return false
+		}
+		if (p === wrapper) break
+	}
+	return true
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/support/rhythm.ts

@@ -0,0 +1,161 @@
+import { childrenOf, descendants, fontSizePx, isHeading, parentOf, styleOf } from "../../../core/page"
+import type { ElementSnapshot, PageSnapshot } from "../../../types"
+import { cardLike, fillDiffers } from "./cards"
+import { alpha, borders, bottom, chain, length, outOfFlow, painted, right, textLines } from "./geometry"
+
+export const paintsEdge = (el: ElementSnapshot, side: string): boolean =>
+	alpha(el, "background-color") > 0.05 || length(el, `border-${side}-width`) > 0 ||
+	!["", "none"].includes(styleOf(el, "box-shadow")) ||
+	!styleOf(el, "background-clip").includes("text") && !styleOf(el, "-webkit-background-clip").includes("text") &&
+	!["", "none"].includes(styleOf(el, "background-image")) &&
+	(styleOf(el, "background-size") === "cover" || styleOf(el, "background-image").includes("gradient(") &&
+		["auto", "auto auto", "100% 100%"].includes(styleOf(el, "background-size")))
+
+const separates = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	borders(el).some(Boolean) || fillDiffers(s, el) || !["", "none"].includes(styleOf(el, "box-shadow"))
+const spacer = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	el.text === "" && !separates(s, el) &&
+	!(alpha(el, "background-color") > 0.05 && chain(s, el).slice(1).some((n) =>
+		!["", "none"].includes(styleOf(n, "background-image")) && paintsEdge(n, "top"))) &&
+	![el, ...descendants(s, el)].some((n) =>
+		/^(img|video|canvas|iframe|svg|input|button)$/.test(n.tag) || n !== el && separates(s, n))
+
+const flow = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	painted(s, el) && !outOfFlow(el) && styleOf(el, "position") !== "sticky" &&
+	Number.parseFloat(styleOf(el, "opacity")) > 0.05 && !["inline", "none"].includes(styleOf(el, "display"))
+
+function flowBoxes(s: PageSnapshot, el: ElementSnapshot, heading: ElementSnapshot): readonly ElementSnapshot[] {
+	if (styleOf(el, "display") === "contents") return childrenOf(s, el).flatMap((c) => flowBoxes(s, c, heading))
+	if (!flow(s, el) || spacer(s, el)) return []
+	if (Math.min(right(el.rect), right(heading.rect)) - Math.max(el.rect.x, heading.rect.x) < 8) return []
+	return [el]
+}
+
+function repeats(s: PageSnapshot, row: ElementSnapshot, heading: ElementSnapshot): boolean {
+	const p = parentOf(s, row)
+	if (!p) return false
+	const kids = childrenOf(s, p)
+	const i = kids.indexOf(row)
+	const laysOut = (n: ElementSnapshot): boolean =>
+		styleOf(n, "display") !== "none" && !outOfFlow(n) && n.rect.width >= 1 && n.rect.height >= 1 && !spacer(s, n)
+	const neighbours = [kids.slice(0, i).reverse().find(laysOut), kids.slice(i + 1).find(laysOut)]
+	const path = (n: ElementSnapshot, stop: ElementSnapshot): readonly string[] => {
+		const steps: string[] = []
+		let current = n
+		while (current !== stop) {
+			const parent = parentOf(s, current)
+			if (!parent) return []
+			steps.unshift(`${current.tag}:${childrenOf(s, parent).indexOf(current)}`)
+			current = parent
+		}
+		return steps
+	}
+	const shape = (root: ElementSnapshot): string[] => {
+		const tags: string[] = []
+		let budget = 24
+		const walk = (node: ElementSnapshot, depth: number): void => {
+			tags.push(node.tag)
+			if (depth === 0) return
+			for (const child of childrenOf(s, node).filter((n) => styleOf(n, "display") !== "none" && !outOfFlow(n) && n.rect.width >= 1 && n.rect.height >= 1)) {
+				if (budget-- <= 0) return
+				walk(child, depth - 1)
+			}
+		}
+		walk(root, 3)
+		return tags
+	}
+	const ownPath = path(heading, row).join("/")
+	const ownShape = shape(row)
+	return neighbours.some((n) => {
+		if (!n || n.tag !== row.tag || ![...descendants(s, n)].some((h) => h.tag === heading.tag && path(h, n).join("/") === ownPath)) return false
+		const other = shape(n)
+		const total = ownShape.length + other.length
+		let shared = 0
+		for (const tag of ownShape) {
+			const at = other.indexOf(tag)
+			if (at >= 0) { shared++; other.splice(at, 1) }
+		}
+		return shared * 2 / total >= 0.7
+	})
+}
+
+export function neighbour(s: PageSnapshot, heading: ElementSnapshot, before: boolean, start = heading): ElementSnapshot | null {
+	let cursor = start
+	for (let depth = 0; depth < 20; depth++) {
+		const parent = parentOf(s, cursor)
+		if (!parent) return null
+		const siblings = childrenOf(s, parent)
+		if (!before && cursor !== heading && repeats(s, cursor, heading)) return null
+		const i = siblings.indexOf(cursor)
+		const choices = (before ? siblings.slice(0, i) : siblings.slice(i + 1))
+			.flatMap((n) => flowBoxes(s, n, heading))
+			.filter((n) => before ? bottom(n.rect) <= start.rect.y + 2 : n.rect.y >= bottom(heading.rect) - 2)
+			.sort((a, b) => before ? bottom(b.rect) - bottom(a.rect) : a.rect.y - b.rect.y)
+		const found = choices[0]
+		if (found) return found
+		if (parent.tag === "body" || separates(s, parent) || !before && (parent.tag === "main" || parent.attributes["role"] === "main")) return null
+		cursor = parent
+	}
+	return null
+}
+
+export function headingCluster(s: PageSnapshot, heading: ElementSnapshot, below: number): ElementSnapshot {
+	let top = heading
+	for (let count = 0; count < 3; count++) {
+		const previous = neighbour(s, heading, true, top)
+		if (!previous || isHeading(previous) || previous.text.length === 0 || previous.text.length > 80 || previous.rect.height > 60) break
+		const gap = top.rect.y - bottom(previous.rect)
+		const words = [previous, ...descendants(s, previous)].filter((n) => n.ownText !== "")
+		const word = words[0] ?? previous
+		const p = parentOf(s, previous)
+		const opens = p !== null && childrenOf(s, p).filter((n) => styleOf(n, "display") !== "none" && n.rect.width >= 1 && n.rect.height >= 1)[0] === previous
+		const lines = words.flatMap((n) => textLines(s, n))
+		const label = fontSizePx(word) <= fontSizePx(heading) && (fontSizePx(word) <= 14 || styleOf(word, "text-transform") === "uppercase" ||
+			length(word, "letter-spacing") >= fontSizePx(word) * 0.05 || opens &&
+			(styleOf(word, "font-style") === "italic" || Number.parseFloat(styleOf(word, "font-weight")) < 400 ||
+				styleOf(word, "color") !== styleOf(heading, "color")))
+		const subtitle = opens && gap <= 2 && fontSizePx(word) <= fontSizePx(heading) && lines.length <= 1
+		if (gap < 0 || gap >= 28 && !(opens && gap < below && gap <= 64) || !(label || subtitle) || lines.length > 1) break
+		top = previous
+	}
+	return top
+}
+
+export function rhythmExempt(s: PageSnapshot, el: ElementSnapshot): boolean {
+	if (!flow(s, el) || el.text.length < 3 || !["h2", "h3", "h4"].includes(el.tag) || paintsEdge(el, "top")) return true
+	return chain(s, el).some((a) => ["blockquote", "q", "nav", "footer"].includes(a.tag) ||
+		a !== el && cardLike(s, a) && a.rect.height < 200)
+}
+
+export function closesInProse(s: PageSnapshot, el: ElementSnapshot, heading: ElementSnapshot, textSize: number): boolean {
+	const blocks = [el, ...descendants(s, el)].filter((n) => ["p", "li", "dd", "div"].includes(n.tag) && n.ownText !== "" && flow(s, n))
+	const last = blocks.sort((a, b) => bottom(b.rect) - bottom(a.rect))[0]
+	return last !== undefined && last.text.length >= 80 && textLines(s, last).length >= 2 &&
+		last.rect.width >= heading.rect.width * 0.5 && fontSizePx(last) < fontSizePx(heading) && fontSizePx(last) <= textSize * 1.25
+}
+
+export function separatesBelow(s: PageSnapshot, el: ElementSnapshot): boolean {
+	if (el.tag === "hr" || el.rect.height <= 4) return true
+	let node: ElementSnapshot | undefined = el
+	let framed = false
+	for (let depth = 0; depth < 8 && node; depth++) {
+		const current = node
+		framed ||= ["top", "left", "right"].some((side) => length(current, `border-${side}-width`) > 0)
+		if (!framed && length(node, "border-bottom-width") > 0 && node.rect.width >= el.rect.width * 0.9 ||
+			/^(img|picture|video|canvas|svg|iframe)$/.test(node.tag) && node.rect.width >= el.rect.width * 0.5 || isHeading(node)) return true
+		node = [...childrenOf(s, node)].reverse().find((n) => styleOf(n, "display") !== "none" &&
+			n.rect.width >= 1 && n.rect.height >= 1 && bottom(n.rect) >= bottom(el.rect) - 2)
+	}
+	return false
+}
+
+export function contentBottom(s: PageSnapshot, el: ElementSnapshot): number {
+	let node = el
+	for (let depth = 0; depth < 8; depth++) {
+		if (paintsEdge(node, "bottom") || /^(img|picture|video|canvas|svg|iframe)$/.test(node.tag)) return Math.min(bottom(node.rect), bottom(el.rect))
+		const lowest = childrenOf(s, node).filter((n) => flow(s, n) && !spacer(s, n)).sort((a, b) => bottom(b.rect) - bottom(a.rect))[0]
+		if (!lowest) return Math.min(bottom(el.rect), bottom(node.rect) - Math.max(0, length(node, "padding-bottom")))
+		node = lowest
+	}
+	return Math.min(bottom(el.rect), bottom(node.rect))
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/text-occlusion.test.ts

@@ -0,0 +1,37 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { textOcclusion } from "./text-occlusion"
+import { lines, marked } from "./support/layout-cases"
+
+const text: NodeSpec = { id: "text", tag: "p", text: "Root cause identified in four minutes", style: { position: "absolute" }, rect: { x: 40, y: 40, width: 300, height: 24 }, lineRects: lines([300], 40, 40) }
+const cover: NodeSpec = { id: "cover", style: { position: "absolute", "z-index": "5", "background-color": "#222" }, rect: { x: 40, y: 40, width: 240, height: 60 } }
+
+test("#given an opaque overlap and a transparent control #then only painted coverage reports", () => {
+	expect(marked(textOcclusion, [text, cover])).toEqual(["#text"])
+	expect(marked(textOcclusion, [text, { ...cover, style: { ...cover.style, opacity: "0" } }])).toEqual([])
+	expect(marked(textOcclusion, [text, { ...cover, style: { position: "absolute", "z-index": "5" } }])).toEqual([])
+})
+
+test("#given pinned overlays and text above its background #then neither is occlusion", () => {
+	expect(marked(textOcclusion, [text, cover])).toEqual(["#text"])
+	expect(marked(textOcclusion, [text, { ...cover, style: { ...cover.style, position: "fixed" } }])).toEqual([])
+	expect(marked(textOcclusion, [{ ...text, style: { position: "absolute", "z-index": "10" } }, cover])).toEqual([])
+})
+
+test("#given a short overlap and a clipping scrollbox #then unseen or tiny coverage does not count", () => {
+	expect(marked(textOcclusion, [text, cover])).toEqual(["#text"])
+	expect(marked(textOcclusion, [text, { ...cover, rect: { x: 40, y: 40, width: 40, height: 60 } }])).toEqual([])
+	expect(marked(textOcclusion, [{ style: { "overflow-y": "auto" }, rect: { x: 20, y: 0, width: 400, height: 30 }, children: [text] }, cover])).toEqual([])
+})
+
+test("#given one pixel type scaled to readable geometry #then it collides while a one pixel dot does not", () => {
+	const caption = { ...text, id: "caption", style: {}, lineRects: lines([240], 40, 40) }
+	const label = { ...text, id: "label", text: "Limited offer today", style: { position: "absolute", "font-size": "1px" }, rect: { x: 40, y: 40, width: 165, height: 16 }, lineRects: lines([165], 40, 40, 16) }
+	expect(marked(textOcclusion, [caption, label])).toEqual(["#caption", "#label"])
+	expect(marked(textOcclusion, [caption, { ...label, rect: { x: 40, y: 40, width: 10, height: 1 }, lineRects: lines([10], 40, 40, 1) }])).toEqual([])
+})
+
+test("#given a single emoji or an edge sliver #then neither is a readable occlusion victim", () => {
+	expect(marked(textOcclusion, [{ ...text, text: "\u{1f600}" }, cover])).toEqual([])
+	expect(marked(textOcclusion, [{ ...text, rect: { x: -250, y: 40, width: 300, height: 24 }, lineRects: lines([300], -250, 40) }, cover])).toEqual([])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/text-occlusion.ts

@@ -0,0 +1,84 @@
+import { descendants, fontSizePx, shortSnippet, styleOf } from "../../core/page"
+import type { PageHit, PageRule } from "../../rule"
+import type { ElementSnapshot, PageSnapshot, Rect } from "../../types"
+import { alpha, borders, bottom, bounds, chain, clipsX, clipsY, intersects, length, painted, right } from "./support/geometry"
+
+const layered = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	chain(s, el).some((n) => /^(absolute|fixed|sticky)$/.test(styleOf(n, "position")))
+const pinned = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	chain(s, el).some((n) => /^(fixed|sticky)$/.test(styleOf(n, "position")))
+const opaque = (el: ElementSnapshot): boolean =>
+	alpha(el, "background-color") > 0.6 || borders(el).filter(Boolean).length >= 2
+const z = (s: PageSnapshot, el: ElementSnapshot): number =>
+	chain(s, el).reduce((sum, n) => sum + (Number.parseInt(styleOf(n, "z-index"), 10) || 0), 0)
+
+function visibleLines(s: PageSnapshot, el: ElementSnapshot): readonly Rect[] {
+	return el.lineRects.flatMap((line) => {
+		let x = Math.max(0, line.x)
+		let y = Math.max(0, line.y)
+		let end = Math.min(s.viewport.width, right(line))
+		let low = Math.min(s.viewport.height, bottom(line))
+		for (const c of chain(s, el)) {
+			if (clipsX(c)) { x = Math.max(x, c.rect.x); end = Math.min(end, right(c.rect)) }
+			if (clipsY(c)) { y = Math.max(y, c.rect.y); low = Math.min(low, bottom(c.rect)) }
+		}
+		return end - x >= 6 && low - y >= 6 ? [{ x, y, width: end - x, height: low - y }] : []
+	})
+}
+
+export const textOcclusion: PageRule = {
+	meta: {
+		id: "text-occlusion", name: "Text occluded by an overlapping element", category: "quality", severity: "warning", engine: "page",
+		description: "An overlapping surface or text run covers readable words.",
+		fixHint: "Separate the layers, remove leaking inline padding, or position the text outside the overlapping surface.",
+	},
+	check: ({ snapshot }) => {
+		const hits: PageHit[] = []
+		const nodes = snapshot.elements.filter((n) => painted(snapshot, n))
+		for (const el of nodes) {
+			if ([...el.ownText].length < 2 || el.rect.width < 6 || el.rect.height < 6 ||
+				el.lineRects.every((r) => r.height <= 1) || alpha(el, "color") <= 0.02 ||
+				chain(snapshot, el).reduce((opacity, n) => opacity * (Number.parseFloat(styleOf(n, "opacity")) || 0), 1) <= 0.02 ||
+				/blur\((?:[4-9]|\d{2,})px\)/.test(styleOf(el, "filter"))) continue
+			const lines = visibleLines(snapshot, el)
+			const total = lines.reduce((n, r) => n + r.width * r.height, 0)
+			if (total === 0) continue
+			const full = bounds(el.lineRects)
+			const visible = bounds(lines)
+			if (full && visible && (visible.width / full.width < 0.25 || el.lineRects.length === 1 && visible.height / full.height < 0.5)) continue
+			const related = new Set([...chain(snapshot, el), ...descendants(snapshot, el)])
+			const cover = nodes.find((other) => {
+				if (related.has(other) || pinned(snapshot, other) || /^(img|video|canvas|picture)$/.test(other.tag) ||
+					styleOf(other, "pointer-events") === "none") return false
+				const text = other.ownText.length >= 2 && other.lineRects.some((r) => r.height > 1)
+				if (!opaque(other) && !text) return false
+				if (text && !layered(snapshot, el) && !layered(snapshot, other)) return false
+				if (z(snapshot, other) < z(snapshot, el) || z(snapshot, other) === z(snapshot, el) && other.index < el.index && !text) return false
+				if (other.ownText === el.ownText && styleOf(other, "font-family") === styleOf(el, "font-family") &&
+					Math.abs(other.rect.x - el.rect.x) < 1 && Math.abs(other.rect.y - el.rect.y) < 1 && !opaque(other)) return false
+				const regions = opaque(other) ? [other.rect] : other.lineRects
+				let covered = 0
+				for (const line of lines) {
+					for (const r of regions) {
+						if (!intersects(line, r)) continue
+						covered += (Math.min(right(line), right(r)) - Math.max(line.x, r.x)) *
+							(Math.min(bottom(line), bottom(r)) - Math.max(line.y, r.y))
+					}
+				}
+				return covered / total >= (opaque(other) ? 0.3 : 0.45)
+			})
+			if (cover) hits.push({ element: el, message: `Text overlaps ${cover.selector}.`, snippet: shortSnippet(el) })
+		}
+		for (const el of nodes) {
+			if (styleOf(el, "display") !== "inline" || !opaque(el)) continue
+			const padding = Math.max(length(el, "padding-top"), length(el, "padding-bottom"))
+			if (padding < 12) continue
+			const expanded = { ...el.rect, y: el.rect.y - padding, height: el.rect.height + padding * 2 }
+			const siblings = nodes.filter((n) => n.parent === el.parent && n !== el)
+			if (siblings.some((n) => n.lineRects.some((r) => intersects(expanded, r)))) {
+				hits.push({ element: el, message: "Inline vertical padding paints over nearby content.", snippet: shortSnippet(el) })
+			}
+		}
+		return hits
+	},
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/text-overflow.test.ts

@@ -0,0 +1,83 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { textOverflow } from "./text-overflow"
+import { lines, marked } from "./support/layout-cases"
+
+const spill: NodeSpec = { id: "spill", tag: "p", text: "A long unbroken line of text spills outside this box.", rect: { x: 40, y: 40, width: 120, height: 40 }, scroll: { clientWidth: 120, scrollWidth: 300 }, lineRects: lines([300], 40, 40) }
+const clip = (node: NodeSpec): NodeSpec => ({ style: { "overflow-x": "hidden" }, rect: { x: 20, y: 20, width: 200, height: 200 }, children: [node] })
+
+test("#given spilled text under a clip and text in free space #then only harmful spill reports", () => {
+	expect(marked(textOverflow, [clip(spill)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [spill])).toEqual([])
+	expect(marked(textOverflow, [clip({ ...spill, lineRects: lines([100], 40, 40) })])).toEqual([])
+})
+
+test("#given explicit scroll and ellipsis affordances #then intentional containment is exempt", () => {
+	expect(marked(textOverflow, [clip(spill)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip({ ...spill, style: { "overflow-x": "auto" } })])).toEqual([])
+	expect(marked(textOverflow, [clip({ ...spill, style: { "overflow-x": "hidden", "text-overflow": "ellipsis" } })])).toEqual([])
+})
+
+test("#given inline text with ineffective ellipsis #then its block container determines the spill", () => {
+	const inline = { ...spill, tag: "span", style: { display: "inline", "overflow-x": "hidden", "text-overflow": "ellipsis" }, scroll: { clientWidth: 0, scrollWidth: 0 } }
+	expect(marked(textOverflow, [clip(inline)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [{ ...clip(inline), style: { "overflow-x": "hidden", "text-overflow": "ellipsis" } }])).toEqual([])
+})
+
+test("#given hidden or vertically clipped replacement text #then no invisible width spill reports", () => {
+	expect(marked(textOverflow, [clip(spill)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip({ ...spill, style: { opacity: "0" } })])).toEqual([])
+	expect(marked(textOverflow, [{ ...clip(spill), rect: { x: 20, y: 0, width: 200, height: 30 }, style: { "overflow-y": "hidden" } }])).toEqual([])
+})
+
+test("#given code in a scrolling page shell #then only a component scroller exempts it", () => {
+	const code = { ...spill, tag: "pre", rect: { x: 1100, y: 40, width: 120, height: 40 }, lineRects: lines([500], 1100, 40) }
+	expect(marked(textOverflow, [{ style: { "overflow-x": "auto" }, rect: { x: 0, y: 0, width: 1280, height: 800 }, children: [code] }])).toEqual(["#spill"])
+	expect(marked(textOverflow, [{ style: { "overflow-x": "auto" }, rect: { x: 1100, y: 40, width: 120, height: 80 }, children: [code] }])).toEqual([])
+})
+
+test("#given code clipped in a terminal window #then its intentional crop is not harmful overflow", () => {
+	expect(marked(textOverflow, [clip(spill)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip({ ...spill, tag: "pre" })])).toEqual([])
+})
+
+test("#given a generated suffix and an image replacement #then only painted overflow reports", () => {
+	const suffix = { ...spill, lineRects: lines([50], 40, 40), after: { content: '" and a very long generated suffix"' } }
+	expect(marked(textOverflow, [clip(suffix)])).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip({ ...spill, lineRects: lines([300], -9999, 40) })])).toEqual([])
+})
+
+test("#given an SVG text node #then HTML overflow rules do not judge its graphics coordinate space", () => {
+	expect(marked(textOverflow, [clip({ tag: "svg", children: [{ ...spill, tag: "text" }] })])).toEqual([])
+})
+
+test("#given a clamped overflow box #then the intentional truncation is not a spill", () => {
+	const clamped = { ...spill, style: { "overflow-x": "hidden", "-webkit-line-clamp": "2" } }
+	expect(marked(textOverflow, [clip(clamped)])).toEqual([])
+	expect(marked(textOverflow, [clip({ ...clamped, style: { ...clamped.style, "-webkit-line-clamp": "none" } })])).toEqual(["#spill"])
+})
+
+test("#given text in the overflow clip margin #then that visible spill is still reported", () => {
+	const label = { ...spill, rect: { x: 40, y: 62, width: 120, height: 20 }, lineRects: lines([300], 40, 62) }
+	const host = { style: { "overflow-x": "clip", "overflow-y": "clip", "overflow-clip-margin": "24px" },
+		rect: { x: 20, y: 20, width: 200, height: 40 }, children: [label] }
+	expect(marked(textOverflow, [host])).toEqual(["#spill"])
+	expect(marked(textOverflow, [{ ...host, style: { ...host.style, "overflow-clip-margin": "0px" } }])).toEqual([])
+	expect(marked(textOverflow, [{ ...host, style: { ...host.style, "overflow-x": "hidden", "overflow-y": "hidden" } }])).toEqual([])
+})
+
+test("#given a running finite width animation #then its temporary opening spill is not reported", () => {
+	const css = "@keyframes type { from { width: 0 } to { width: 100% } }"
+	const style = { "animation-name": "type", "animation-iteration-count": "1", "animation-play-state": "running" }
+	const moving = { ...spill, motion: ["width"], style }
+	expect(marked(textOverflow, [clip(moving)], { cssText: [css] })).toEqual([])
+	expect(marked(textOverflow, [clip({ ...moving, motion: [] })], { cssText: [css] })).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip({ ...moving, style: { ...style, "animation-iteration-count": "infinite" } })], { cssText: [css] })).toEqual(["#spill"])
+	expect(marked(textOverflow, [clip(moving)])).toEqual(["#spill"])
+})
+
+test("#given a running inline size transition #then a finite named transition can explain the opening box", () => {
+	const moving = { ...spill, motion: ["inline-size"], style: { "transition-property": "inline-size", "transition-duration": "200ms" } }
+	expect(marked(textOverflow, [clip(moving)])).toEqual([])
+	expect(marked(textOverflow, [clip({ ...moving, style: { ...moving.style, "transition-duration": "0s" } })])).toEqual(["#spill"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/text-overflow.ts

@@ -0,0 +1,72 @@
+import { descendants, fontSizePx, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import type { ElementSnapshot, PageSnapshot, Rect } from "../../types"
+import { alpha, borders, bottom, bounds, chain, clipRect, clipsX, clipsY, intersects, length, painted, right, scrollsX, textLines } from "./support/geometry"
+import { shell } from "./support/clipping"
+import { openingWidth } from "./support/motion"
+
+const truncates = (el: ElementSnapshot): boolean =>
+	!["inline", "contents"].includes(styleOf(el, "display")) && clipsX(el) &&
+	(!["", "clip"].includes(styleOf(el, "text-overflow")) || Number.parseInt(styleOf(el, "-webkit-line-clamp"), 10) > 0)
+
+function harm(s: PageSnapshot, el: ElementSnapshot, box: Rect, text: Rect): boolean {
+	const code = chain(s, el).some((n) => ["pre", "code"].includes(n.tag))
+	const tolerance = fontSizePx(el) * 0.25
+	let cut = false
+	for (const c of chain(s, el)) {
+		if (styleOf(c, "display") === "inline" || !clipsX(c)) continue
+		const clip = clipRect(c)
+		if (text.x < clip.x - 1 || right(text) > right(clip) + 1) {
+			if (!code) return true
+			if (text.x < clip.x - 1 && clip.x > tolerance ||
+				right(text) > right(clip) + 1 && right(clip) < s.viewport.width - tolerance) cut = true
+		}
+	}
+	if (cut) return false
+	if (text.x <= tolerance || right(text) >= s.viewport.width - tolerance) return true
+	const related = new Set([...chain(s, el), ...descendants(s, el)])
+	return s.elements.some((other) => {
+		if (related.has(other) || !painted(s, other) || other.rect.width <= 2 || other.rect.height <= 2) return false
+		if (other.ownText === "" && !/^(img|video|canvas|svg|picture)$/.test(other.tag) && alpha(other, "background-color") < 0.25 && !borders(other).some(Boolean) &&
+			["", "none"].includes(styleOf(other, "background-image"))) return false
+		const r = other.rect
+		if (r.x <= box.x && right(r) >= right(box) && r.y <= box.y && bottom(r) >= bottom(box)) return false
+		return intersects(text, r) && (right(r) > right(box) && r.x < right(text) || r.x < box.x && right(r) > text.x)
+	})
+}
+
+export const textOverflow: PageRule = {
+	meta: {
+		id: "text-overflow", name: "Content overflowing its container", category: "quality", severity: "warning", engine: "page",
+		description: "Text spills out of its box into a clip, another element, or the viewport edge.",
+		fixHint: "Allow wrapping, constrain the content width, or provide a deliberate horizontal scroll region.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap((el) => {
+		if (el.ownText === "" || /^(input|textarea|select|option|svg|path|script|style)$/.test(el.tag) || !painted(snapshot, el)) return []
+		const path = chain(snapshot, el)
+		if (path.some((n) => n.tag === "svg")) return []
+		if (openingWidth(snapshot, el)) return []
+		const code = path.some((n) => ["pre", "code", "samp", "kbd"].includes(n.tag))
+		if (path.some((n) => scrollsX(n) && !(code && n !== el && shell(snapshot, n))) || path.some(truncates)) return []
+		const text = bounds(textLines(snapshot, el))
+		if (!text) return []
+		if (path.some((c) => clipsY(c) && (text.y >= bottom(clipRect(c)) || bottom(text) <= clipRect(c).y))) return []
+		if (path.some((c) => styleOf(c, "display") !== "inline" && clipsX(c) && (right(text) <= clipRect(c).x || text.x >= right(clipRect(c))))) return []
+		const box = styleOf(el, "display") === "inline"
+			? path.slice(1).find((c) => c.scroll.clientWidth > 0 && styleOf(c, "display") !== "inline") ?? el
+			: el
+		const start = box.rect.x + length(box, "border-left-width")
+		const end = start + (box.scroll.clientWidth > 0 ? box.scroll.clientWidth : box.rect.width)
+		const generated = [el.before, el.after].some((p) => p !== null && /["'][^"']+["']/.test(p.style["content"] ?? "") &&
+			p.style["display"] !== "none")
+		const reach = generated && el.scroll.scrollWidth > el.scroll.clientWidth
+			? { ...text, width: Math.max(text.width, el.scroll.scrollWidth) } : text
+		const delta = Math.max(right(reach) - end, start - reach.x)
+		const drawn = alpha(box, "background-color") > 0 || borders(box).some(Boolean)
+		const pastContent = Math.max(right(text) - end + length(box, "padding-right"), start + length(box, "padding-left") - text.x)
+		const paintedSpill = !code && drawn && !clipsX(box) && delta < 16 &&
+			delta >= Math.max(fontSizePx(el) * 0.25, 2) && pastContent >= 15
+		if (!(delta >= 16 && harm(snapshot, el, box.rect, reach) || paintedSpill)) return []
+		return [{ element: el, message: `Text extends ${Math.round(delta)}px past its container.`, snippet: shortSnippet(el) }]
+	}),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/unbalanced-heading.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test"
+import { unbalancedHeading } from "./unbalanced-heading"
+import { lines, marked } from "./support/layout-cases"
+
+const heading = { id: "heading", tag: "h2", text: "Design that holds up under real content and real people", rect: { x: 24, y: 24, width: 500, height: 60 }, lineRects: lines([500, 80]) }
+
+test("#given two heading lines with a tiny tail #then only the unbalanced heading reports", () => {
+	expect(marked(unbalancedHeading, [heading])).toEqual(["#heading"])
+	expect(marked(unbalancedHeading, [{ ...heading, lineRects: lines([500, 400]) }])).toEqual([])
+})
+
+test("#given authored balance and deliberate breaks #then heading line intent is respected", () => {
+	expect(marked(unbalancedHeading, [heading])).toEqual(["#heading"])
+	expect(marked(unbalancedHeading, [{ ...heading, style: { "text-wrap": "balance" } }])).toEqual([])
+	expect(marked(unbalancedHeading, [{ ...heading, children: [{ tag: "br" }] }])).toEqual([])
+})
+
+test("#given long statements and two word headings #then the balance rule stands down", () => {
+	expect(marked(unbalancedHeading, [heading])).toEqual(["#heading"])
+	expect(marked(unbalancedHeading, [{ ...heading, lineRects: lines([500, 500, 500, 80]) }])).toEqual([])
+	expect(marked(unbalancedHeading, [{ ...heading, text: "Documentation hub" }])).toEqual([])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/unbalanced-heading.ts

@@ -0,0 +1,22 @@
+import { isHeading, shortSnippet } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { measuredLines, oneFace, wordsOf, wrapIs } from "./support/line-breaks"
+
+export const unbalancedHeading: PageRule = {
+	meta: {
+		id: "unbalanced-heading", name: "Unbalanced heading", category: "quality", severity: "advisory", engine: "page",
+		description: "The last line of a heading is much shorter than the line above.",
+		fixHint: "Use text-wrap: balance or rewrite the heading to keep its lines near even.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap((el) => {
+		if (!isHeading(el) || wrapIs(el, "balance") || wordsOf(el).length < 3) return []
+		const lines = measuredLines(snapshot, el)
+		const tail = lines.at(-1)
+		const above = lines.at(-2)
+		if (lines.length < 2 || lines.length > 3 || !tail || !above || tail.width >= above.width * 0.35) return []
+		const widest = Math.max(...lines.map((l) => l.width))
+		const total = lines.reduce((n, l) => n + l.width, 0)
+		if (oneFace(snapshot, el) && widest * el.text.length / total < 20) return []
+		return [{ element: el, message: `The last line is ${Math.round(tail.width / above.width * 100)}% as wide as the line above.`, snippet: shortSnippet(el) }]
+	}),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/viewport-reflow.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { viewportReflow } from "./viewport-reflow"
+import { selectors } from "./support/layout-cases"
+
+for (const width of [320, 375, 768, 1024, 1440]) {
+	test(`#given an overflowing document at ${width}px #then a page finding names the furthest element`, () => {
+		const base = buildSnapshot([
+			{ id: "offender", rect: { x: 20, width: width + 40 } },
+			{ id: "scroll", style: { "overflow-x": "auto" }, children: [{ id: "track", rect: { width: width * 3 } }] },
+			{ id: "hidden", style: { opacity: "0" }, rect: { width: width * 4 } },
+		], { viewport: { width, height: 800 } })
+		const snapshot = { ...base, document: { ...base.document, scrollWidth: width + 60 } }
+		expect(selectors(viewportReflow, snapshot)).toEqual(["page"])
+		expect(viewportReflow.check({ snapshot, config: {} })[0]?.message).toContain("#offender")
+		expect(selectors(viewportReflow, base)).toEqual([])
+	})
+}
+
+test("#given overflow without a measured offender #then the document still fails reflow", () => {
+	const base = buildSnapshot([])
+	const snapshot = { ...base, document: { ...base.document, scrollWidth: 1300 } }
+	expect(selectors(viewportReflow, snapshot)).toEqual(["page"])
+	expect(selectors(viewportReflow, base)).toEqual([])
+})
+
+test("#given overflowing words and a wider clipped track #then the real uncontained text owns the overflow", () => {
+	const base = buildSnapshot([
+		{ id: "words", text: "Unbroken text", rect: { x: 20, width: 200 }, lineRects: [{ x: 20, y: 0, width: 1400, height: 20 }] },
+		{ id: "window", style: { "overflow-x": "hidden" }, rect: { width: 1280 }, children: [{ id: "track", rect: { width: 6000 } }] },
+	])
+	const snapshot = { ...base, document: { ...base.document, scrollWidth: 1420 } }
+	expect(viewportReflow.check({ snapshot, config: {} })[0]?.message).toContain("#words")
+})