oh-my-opencode 5.1.48 → 5.1.54

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/edge-flush-cards.test.ts

@@ -0,0 +1,43 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { edgeFlushCards } from "./edge-flush-cards"
+import { marked } from "./support/layout-cases"
+
+const row = (end = 604, extra: Partial<NodeSpec> = {}): NodeSpec => ({
+	id: "row", style: { "overflow-x": "auto", "background-color": "#ddd" }, rect: { x: 24, y: 24, width: 600, height: 160 },
+	scroll: { scrollWidth: 1200, clientWidth: 600 }, children: [
+		{ id: "card", style: { "background-color": "#fff" }, rect: { x: 40, y: 40, width: end - 16, height: 90 } },
+		{ style: { "background-color": "#fff" }, rect: { x: 660, y: 40, width: 560, height: 90 } },
+	], ...extra,
+})
+
+test("#given asymmetric card edges beside even gutters #then only the cut edge reports", () => {
+	expect(marked(edgeFlushCards, [row()])).toEqual(["#row"])
+	expect(marked(edgeFlushCards, [row(584)])).toEqual([])
+	expect(marked(edgeFlushCards, [row(700)])).toEqual([])
+})
+
+test("#given lone cards and vertical only scrollers #then no horizontal row is charged", () => {
+	expect(marked(edgeFlushCards, [row()])).toEqual(["#row"])
+	expect(marked(edgeFlushCards, [row(604, { children: [{ style: { "background-color": "#fff" }, rect: { x: 40, y: 40, width: 588, height: 90 } }] })])).toEqual([])
+	expect(marked(edgeFlushCards, [row(604, { style: { "overflow-x": "hidden", "overflow-y": "auto" } })])).toEqual([])
+})
+
+test("#given table cells in a scroll region #then table geometry is not treated as cards", () => {
+	expect(marked(edgeFlushCards, [row()])).toEqual(["#row"])
+	expect(marked(edgeFlushCards, [row(604, { children: [
+		{ tag: "td", style: { "background-color": "#fff" }, rect: { x: 40, y: 40, width: 588, height: 90 } },
+		{ tag: "td", style: { "background-color": "#fff" }, rect: { x: 660, y: 40, width: 560, height: 90 } },
+	] })])).toEqual([])
+})
+
+test("#given a transparent scroller in a centered column #then its inset is not a page gutter", () => {
+	const transparent = (x: number): NodeSpec => row(604, {
+		style: { "overflow-x": "auto" }, rect: { x, y: 24, width: 600, height: 160 }, children: [
+			{ style: { "background-color": "#fff" }, rect: { x: x + 4, y: 40, width: 560, height: 90 } },
+			{ style: { "background-color": "#fff" }, rect: { x: x + 620, y: 40, width: 560, height: 90 } },
+		],
+	})
+	expect(marked(edgeFlushCards, [transparent(24)])).toEqual([])
+	expect(marked(edgeFlushCards, [transparent(200)])).toEqual(["#row"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/edge-flush-cards.ts

@@ -0,0 +1,47 @@
+import { ancestors, descendants, isRendered, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { alpha, borders, chain, length, painted, right, scrollsX } from "./support/geometry"
+
+export const edgeFlushCards: PageRule = {
+	meta: {
+		id: "edge-flush-cards", name: "Cards flush against the scroller edge", category: "quality", severity: "warning", engine: "page",
+		description: "A card row keeps a gutter on one side but touches or slightly crosses the opposite clipping edge.",
+		fixHint: "Size each panel to its scroll container and keep an equal inset at both edges.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap((scroller) => {
+		if (scroller.tag === "body" || !scrollsX(scroller) || !painted(snapshot, scroller) ||
+			scroller.scroll.scrollWidth <= scroller.scroll.clientWidth + 8 ||
+			scroller.rect.width < 120 || scroller.rect.height < 60 || scroller.rect.y > snapshot.viewport.height * 2) return []
+		const cards = [...descendants(snapshot, scroller)].filter((el) => {
+			if (!isRendered(snapshot, el) || el.rect.width < 80 || el.rect.height < 40 ||
+				/^(table|thead|tbody|tfoot|tr|td|th|col|colgroup)$/.test(el.tag) ||
+				/^(row|cell|gridcell|rowgroup|columnheader|rowheader)$/.test(el.attributes["role"] ?? "")) return false
+			if (alpha(el, "background-color") <= 0.5 && borders(el).filter(Boolean).length < 2) return false
+			for (const a of ancestors(snapshot, el)) {
+				if (a === scroller) return true
+				if (scrollsX(a)) return false
+			}
+			return false
+		})
+		if (cards.length < 2 || Math.min(...cards.map((c) => right(c.rect))) > Math.max(...cards.map((c) => c.rect.x)) + 1) return []
+		const left = scroller.rect.x + length(scroller, "border-left-width")
+		const end = left + scroller.scroll.clientWidth
+		const gutter = (side: "left" | "right"): boolean => {
+			const inset = side === "left" ? scroller.rect.x : snapshot.viewport.width - right(scroller.rect)
+			if (inset < 12 || inset > 48) return false
+			return !chain(snapshot, scroller).slice(0, 7).some((n) => {
+				if (n.tag === "body") return false
+				const near = side === "left" ? Math.abs(n.rect.x - scroller.rect.x) <= 2 : Math.abs(right(n.rect) - right(scroller.rect)) <= 2
+				return near && (alpha(n, "background-color") > 0 || !["", "none"].includes(styleOf(n, "background-image")) ||
+					!["", "none"].includes(styleOf(n, "box-shadow")) || borders(n)[side === "left" ? 3 : 1])
+			})
+		}
+		const flush = cards.filter((c) => {
+			const start = c.rect.x - left
+			const gap = end - right(c.rect)
+			return (start >= 6 && gap < 8 && gap > -24 && !(gap >= 0 && gutter("right"))) ||
+				(gap >= 6 && start < 8 && start > -24 && !(start >= 0 && gutter("left")))
+		})
+		return flush.length === 0 ? [] : [{ element: scroller, message: `${flush.length} cards touch a scroll edge while keeping an opposite gutter.`, snippet: shortSnippet(scroller) }]
+	}),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/first-viewport-column-overflow.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { firstViewportColumnOverflow } from "./first-viewport-column-overflow"
+import { marked } from "./support/layout-cases"
+
+const opening = (short: Partial<NodeSpec> = {}, tall: Partial<NodeSpec> = {}): NodeSpec => ({
+	id: "opening", style: { display: "grid" }, rect: { x: 20, y: 20, width: 1200, height: 1600 }, children: [
+		{ id: "short", rect: { x: 40, y: 40, width: 500, height: 1500 }, children: [{ tag: "p", text: "Short opening copy", rect: { x: 40, y: 40, width: 500, height: 200 } }], ...short },
+		{ rect: { x: 640, y: 40, width: 500, height: 1500 }, children: [{ text: "A tall block", rect: { x: 640, y: 40, width: 500, height: 1500 } }], ...tall },
+	],
+})
+
+test("#given stretched grid cells with unequal content #then measured content exposes the tall opening", () => {
+	expect(marked(firstViewportColumnOverflow, [opening()])).toEqual(["#opening"])
+	expect(marked(firstViewportColumnOverflow, [opening({}, { children: [{ text: "Fits", rect: { x: 640, y: 40, width: 500, height: 600 } }] })])).toEqual([])
+})
+
+test("#given stacked columns or navigation rails #then intentional short regions are excluded", () => {
+	expect(marked(firstViewportColumnOverflow, [opening()])).toEqual(["#opening"])
+	expect(marked(firstViewportColumnOverflow, [opening({ tag: "nav" })])).toEqual([])
+	expect(marked(firstViewportColumnOverflow, [opening({ style: { position: "sticky" } })])).toEqual([])
+	expect(marked(firstViewportColumnOverflow, [opening({}, { rect: { x: 40, y: 300, width: 500, height: 1500 } })])).toEqual([])
+})
+
+test("#given tall content cut inside its own scrolling column #then only visible content is measured", () => {
+	expect(marked(firstViewportColumnOverflow, [opening()])).toEqual(["#opening"])
+	expect(marked(firstViewportColumnOverflow, [opening({}, { style: { "overflow-y": "auto" }, rect: { x: 640, y: 40, width: 500, height: 500 } })])).toEqual([])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/first-viewport-column-overflow.ts

@@ -0,0 +1,43 @@
+import { ancestors, childrenOf, descendants, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { bottom, chain, clipsY, hasRole, outOfFlow, painted, right } from "./support/geometry"
+
+export const firstViewportColumnOverflow: PageRule = {
+	meta: {
+		id: "first-viewport-column-overflow", name: "One column stretches the first viewport", category: "quality", severity: "warning", engine: "page",
+		description: "An opening row has one column extending far below the fold while its sibling fits on one screen.",
+		fixHint: "Balance the opening columns, cap the longer one, or let its remaining content flow below the row.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap((el) => {
+		const { width, height } = snapshot.viewport
+		if (!/^(inline-)?(flex|grid)$/.test(styleOf(el, "display")) || !painted(snapshot, el) ||
+			el.rect.width < width * 0.5 || el.rect.y >= height * 0.9 || bottom(el.rect) <= height) return []
+		const rail = (n: typeof el): boolean => {
+			if (n.tag === "nav" || hasRole(n, ["navigation", "tablist"]) || styleOf(n, "position") === "sticky") return true
+			const nodes = [n, ...descendants(snapshot, n)].filter((c) => c.ownText !== "" && painted(snapshot, c))
+			return nodes.length >= 3 && nodes.filter((c) => chain(snapshot, c).some((a) => a.tag === "a" || hasRole(a, ["tab", "menuitem"]))).length / nodes.length >= 0.8
+		}
+		const cols = childrenOf(snapshot, el).flatMap((child) => {
+			const share = child.rect.width / el.rect.width
+			if (!painted(snapshot, child) || outOfFlow(child) || rail(child) || share < 0.25 || share > 0.9 || child.rect.height < 40) return []
+			let end = child.rect.y
+			for (const d of descendants(snapshot, child)) {
+				if (!painted(snapshot, d) || [d, ...ancestors(snapshot, d)].some((n) => n !== el && outOfFlow(n))) continue
+				let visible = bottom(d.rect)
+				for (const a of ancestors(snapshot, d)) {
+					if (a === el) break
+					if (clipsY(a)) visible = Math.min(visible, bottom(a.rect))
+				}
+				end = Math.max(end, visible)
+			}
+			return end - child.rect.y < 1 ? [] : [{ rect: child.rect, height: end - child.rect.y }]
+		}).sort((a, b) => b.height - a.height)
+		const tall = cols[0]
+		if (!tall || tall.height <= height * 1.4) return []
+		const short = cols.slice(1).filter((c) =>
+			!(tall.rect.x < right(c.rect) - 1 && c.rect.x < right(tall.rect) - 1) &&
+			Math.abs(tall.rect.y - c.rect.y) <= height * 0.25).sort((a, b) => a.height - b.height)[0]
+		if (!short || short.height > height) return []
+		return [{ element: el, message: `Opening columns use ${Math.round(tall.height / height * 100)}% and ${Math.round(short.height / height * 100)}% of the viewport height.`, snippet: shortSnippet(el) }]
+	}),
+}

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

@@ -0,0 +1,67 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { headingRhythm } from "./heading-rhythm"
+import { lines, marked } from "./support/layout-cases"
+
+const group = (id: string, y: number, above = 0, below = 40): NodeSpec => ({
+	style: { "border-top-width": "1px", "border-top-style": "solid", "border-top-color": "#333" },
+	rect: { x: 24, y, width: 560, height: 220 }, children: [
+		{ tag: "p", text: "A previous paragraph with enough prose to be read as the closing block of the previous section.", rect: { x: 24, y: y + 10, width: 560, height: 48 }, lineRects: lines([550, 400], 24, y + 10) },
+		{ id, tag: "h2", text: "Section heading", style: { "font-size": "28px" }, rect: { x: 24, y: y + 58 + above, width: 560, height: 36 } },
+		{ tag: "p", text: "The introduced content belongs to this heading.", rect: { x: 24, y: y + 94 + above + below, width: 560, height: 48 } },
+	],
+})
+
+test("#given multiple crowded headings beside healthy gaps #then only crowded headings report", () => {
+	expect(marked(headingRhythm, [group("one", 0), group("two", 240), group("healthy", 480, 64, 16)])).toEqual(["#one", "#two"])
+	expect(marked(headingRhythm, [group("one", 0, 64, 16), group("two", 240, 64, 16)])).toEqual([])
+})
+
+test("#given one crowded heading #then the page minimum prevents a single local judgement", () => {
+	expect(marked(headingRhythm, [group("one", 0), group("two", 240)])).toEqual(["#one", "#two"])
+	expect(marked(headingRhythm, [group("one", 0)])).toEqual([])
+})
+
+test("#given equal gaps under running prose #then headings still attach to the previous block", () => {
+	expect(marked(headingRhythm, [group("one", 0, 24, 24), group("two", 240, 20, 24)])).toEqual(["#one", "#two"])
+	expect(marked(headingRhythm, [group("one", 0, 24, 20), group("two", 240, 24, 20)])).toEqual([])
+})
+
+test("#given headings following headings rather than prose #then titling groups do not count", () => {
+	const titles = (id: string, y: number) => {
+		const g = group(id, y)
+		return { ...g, children: (g.children ?? []).map((n, i) => i === 0 ? { ...n, tag: "h2" } : n) }
+	}
+	expect(marked(headingRhythm, [titles("one", 0), titles("two", 240)])).toEqual([])
+})
+
+test("#given short two line labels with even gaps #then they are not running prose", () => {
+	const labels = (id: string, y: number) => {
+		const g = group(id, y, 24, 24)
+		return { ...g, children: (g.children ?? []).map((n, i) => i === 0 ? { ...n, text: "A short label" } : n) }
+	}
+	expect(marked(headingRhythm, [labels("one", 0), labels("two", 240)])).toEqual([])
+})
+
+test("#given a preceding label larger than its heading #then it is not folded into the heading", () => {
+	const small = (id: string, y: number): NodeSpec => {
+		const g = group(id, y)
+		return { ...g, children: (g.children ?? []).map((n, i) => i === 0
+			? { ...n, text: "Closing copy", style: { "font-size": "14px" }, rect: { x: 24, y: y + 10, width: 560, height: 24 } }
+			: i === 1 ? { ...n, style: { "font-size": "13px" } } : n) }
+	}
+	expect(marked(headingRhythm, [small("one", 0), small("two", 240)])).toEqual(["#one", "#two"])
+})
+
+test("#given alike title rows separated by other content #then distant rows do not stop the neighbour walk", () => {
+	const rows = (id: string, y: number): NodeSpec => {
+		const g = group(id, y)
+		const nodes = g.children ?? []
+		const wrapped: NodeSpec[] = nodes.map((n, i) => i === 0 ? n : {
+			attributes: { class: "row" }, rect: n.rect ?? {}, children: [n],
+		})
+		return { ...g, children: [...wrapped, { attributes: { class: "row" }, rect: { x: 24, y: y + 210, width: 560, height: 36 },
+			children: [{ tag: "h2", text: "A later title", rect: { x: 24, y: y + 210, width: 560, height: 36 } }] }] }
+	}
+	expect(marked(headingRhythm, [rows("one", 0), rows("two", 300)])).toEqual(["#one", "#two"])
+})

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

@@ -0,0 +1,30 @@
+import { fontSizePx, shortSnippet } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { bottom, length } from "./support/geometry"
+import { closesInProse, contentBottom, headingCluster, neighbour, paintsEdge, rhythmExempt, separatesBelow } from "./support/rhythm"
+
+export const headingRhythm: PageRule = {
+	meta: {
+		id: "heading-rhythm", name: "Heading crowded against the previous block", category: "quality", severity: "warning", engine: "page",
+		description: "Several headings sit closer to preceding content than to the content they introduce.",
+		fixHint: "Give section headings more space above than below so each title binds to its own content.",
+	},
+	check: ({ snapshot }) => {
+		const hits = snapshot.elements.flatMap((el) => {
+			if (rhythmExempt(snapshot, el)) return []
+			const next = neighbour(snapshot, el, false)
+			if (!next) return []
+			const below = Math.max(0, next.rect.y - bottom(el.rect))
+			if (below < 6 || below > 160) return []
+			const top = headingCluster(snapshot, el, below)
+			const previous = neighbour(snapshot, el, true, top)
+			if (!previous || separatesBelow(snapshot, previous)) return []
+			const above = Math.max(0, top.rect.y - contentBottom(snapshot, previous) + (paintsEdge(top, "top") ? 0 : length(top, "padding-top")))
+			const crowded = above < below * 0.75 && below - above >= 12
+			const body = snapshot.elements.find((n) => n.tag === "body")
+			const even = above <= below + 2 && closesInProse(snapshot, previous, el, Math.max(body ? fontSizePx(body) : 16, fontSizePx(next)))
+			return crowded || even ? [{ element: el, message: `Heading has ${Math.round(above)}px above and ${Math.round(below)}px below.`, snippet: shortSnippet(el) }] : []
+		})
+		return hits.length >= 2 ? hits : []
+	},
+}

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

@@ -0,0 +1,21 @@
+import type { Rule } from "../../rule"
+import { bodyTextViewportEdge } from "./body-text-viewport-edge"
+import { clippedOverflowContainer } from "./clipped-overflow-container"
+import { contentHiddenAtRest } from "./content-hidden-at-rest"
+import { crampedPadding } from "./cramped-padding"
+import { edgeFlushCards } from "./edge-flush-cards"
+import { firstViewportColumnOverflow } from "./first-viewport-column-overflow"
+import { headingRhythm } from "./heading-rhythm"
+import { monotonousSpacing } from "./monotonous-spacing"
+import { nestedCards } from "./nested-cards"
+import { straggler } from "./straggler"
+import { textOcclusion } from "./text-occlusion"
+import { textOverflow } from "./text-overflow"
+import { unbalancedHeading } from "./unbalanced-heading"
+import { viewportReflow } from "./viewport-reflow"
+
+export const LAYOUT_RULES: readonly Rule[] = [
+	nestedCards, monotonousSpacing, edgeFlushCards, textOcclusion, firstViewportColumnOverflow,
+	crampedPadding, bodyTextViewportEdge, textOverflow, clippedOverflowContainer, headingRhythm,
+	straggler, unbalancedHeading, contentHiddenAtRest, viewportReflow,
+]

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/monotonous-spacing.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test"
+import { monotonousSpacing } from "./monotonous-spacing"
+import { marked } from "./support/layout-cases"
+
+test("#given ten repeated utility gaps and varied controls #then only the repeated scale reports", () => {
+	expect(marked(monotonousSpacing, Array.from({ length: 10 }, () => ({ attributes: { class: "p-4" } })))).toEqual(["page"])
+	expect(marked(monotonousSpacing, Array.from({ length: 10 }, (_, i) => ({ attributes: { class: `p-${i + 1}` } })))).toEqual([])
+})
+
+test("#given repeated CSS lengths and zero resets #then only nonzero dominant spacing reports", () => {
+	expect(marked(monotonousSpacing, [], { cssText: Array.from({ length: 10 }, (_, i) => `.x${i} { padding: 16px; }`) })).toEqual(["page"])
+	expect(marked(monotonousSpacing, Array.from({ length: 20 }, () => ({ attributes: { class: "p-0" } })))).toEqual([])
+})
+
+test("#given rem declarations with a small sample #then the ten sample floor is enforced", () => {
+	const css = Array.from({ length: 10 }, (_, i) => `.x${i} { margin: 1rem; }`)
+	expect(marked(monotonousSpacing, [], { cssText: css })).toEqual(["page"])
+	expect(marked(monotonousSpacing, [], { cssText: css.slice(0, 9) })).toEqual([])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/monotonous-spacing.ts

@@ -0,0 +1,32 @@
+import type { PageRule } from "../../rule"
+
+export const monotonousSpacing: PageRule = {
+	meta: {
+		id: "monotonous-spacing", name: "Monotonous spacing", category: "slop", severity: "warning", engine: "page",
+		description: "One spacing value dominates the page instead of separating related groups from sections.",
+		fixHint: "Keep related items close and give separate sections a larger gap.",
+	},
+	check: ({ snapshot }) => {
+		const values: number[] = []
+		const css = [...snapshot.cssText, ...snapshot.elements.map((el) => el.attributes["style"] ?? "")].join("\n")
+		for (const m of css.matchAll(/(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi)) {
+			const v = Number(m[1])
+			if (v > 0 && v < 200) values.push(v)
+		}
+		for (const m of css.matchAll(/(?:gap|row-gap|column-gap)\s*:\s*(\d+)px/gi)) values.push(Number(m[1]))
+		for (const el of snapshot.elements) {
+			for (const m of (el.attributes["class"] ?? "").matchAll(/\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g)) values.push(Number(m[1]) * 4)
+		}
+		for (const m of css.matchAll(/(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d*\.?\d+)rem/gi)) {
+			const v = Math.round(Number(m[1]) * 16)
+			if (v > 0 && v < 200) values.push(v)
+		}
+		const rounded = values.map((v) => Math.round(v / 4) * 4)
+		if (rounded.length < 10) return []
+		const counts = new Map<number, number>()
+		for (const v of rounded) counts.set(v, (counts.get(v) ?? 0) + 1)
+		const dominant = [...counts].sort((a, b) => b[1] - a[1])[0]
+		if (!dominant || dominant[0] === 0 || dominant[1] / rounded.length <= 0.6 || [...counts.keys()].filter((v) => v > 0).length > 3) return []
+		return [{ element: null, message: `${dominant[0]}px accounts for ${dominant[1]} of ${rounded.length} spacing declarations.`, snippet: `${Math.round(dominant[1] / rounded.length * 100)}% repeated spacing` }]
+	},
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/nested-cards.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "bun:test"
+import type { NodeSpec } from "../../testing/build-snapshot"
+import { nestedCards } from "./nested-cards"
+import { border, marked, rounded } from "./support/layout-cases"
+
+const inner: NodeSpec = { id: "inner", style: { ...border, ...rounded }, rect: { x: 40, y: 40, width: 240, height: 140 }, children: [
+	{ tag: "p", text: "An inner group with a paragraph of copy." }, { tag: "p", text: "A second paragraph makes this a content surface." },
+] }
+const outer = (child: NodeSpec): NodeSpec => ({ id: "outer", style: { ...border, ...rounded }, rect: { x: 20, y: 20, width: 400, height: 300 }, children: [child] })
+
+test("#given bordered inner cards beside fill-only and hidden groups #then only a visible framed card reports", () => {
+	expect(marked(nestedCards, [outer(inner)])).toEqual(["#inner"])
+	expect(marked(nestedCards, [outer({ ...inner, style: { ...rounded, "background-color": "#eee" } })])).toEqual([])
+	expect(marked(nestedCards, [outer({ ...inner, style: { ...border, ...rounded, opacity: "0" } })])).toEqual([])
+})
+
+test("#given labels and popups inside cards #then they are not nested surfaces", () => {
+	expect(marked(nestedCards, [outer(inner)])).toEqual(["#inner"])
+	for (const change of [{ attributes: { role: "menu" } }, { style: { ...border, ...rounded, position: "absolute" } }, { text: "Small label", children: [], rect: { x: 40, y: 40, width: 180, height: 32 } }]) {
+		expect(marked(nestedCards, [outer({ ...inner, ...change })])).toEqual([])
+	}
+})
+
+test("#given a card header sharing three edges #then it is part of its outer card", () => {
+	expect(marked(nestedCards, [outer(inner)])).toEqual(["#inner"])
+	expect(marked(nestedCards, [outer({ ...inner, rect: { x: 21, y: 21, width: 398, height: 140 } })])).toEqual([])
+})
+
+test("#given an embedded figure or a dialog panel #then its framing is not a nested card", () => {
+	expect(marked(nestedCards, [outer(inner)])).toEqual(["#inner"])
+	expect(marked(nestedCards, [outer({ ...inner, children: [{ tag: "canvas", rect: { width: 220, height: 120 } }, { tag: "p", text: "Chart caption." }] })])).toEqual([])
+	expect(marked(nestedCards, [{ attributes: { role: "dialog" }, children: [outer(inner)] }])).toEqual([])
+})
+
+test("#given a hidden audio source with visible player controls #then player chrome is not a nested surface", () => {
+	expect(marked(nestedCards, [outer(inner)])).toEqual(["#inner"])
+	expect(marked(nestedCards, [outer({ ...inner, children: [
+		{ tag: "audio", rect: { width: 0, height: 0 } },
+		{ tag: "p", text: "Sample audio speaker A" },
+		{ tag: "button", attributes: { "aria-label": "Play" } },
+		{ attributes: { role: "slider", "aria-label": "Audio progress" } },
+	] })])).toEqual([])
+})
+
+test("#given repeated inner cards in one panel #then only the first visible card reports", () => {
+	const second = { ...inner, id: "second", rect: { x: 40, y: 200, width: 240, height: 140 } }
+	expect(marked(nestedCards, [{ ...outer(inner), children: [inner, second] }])).toEqual(["#inner"])
+	expect(marked(nestedCards, [{ ...outer(inner), children: [{ ...inner, attributes: { "data-detect-ignore": "nested-cards" } }, second] }])).toEqual(["#second"])
+})
+
+test("#given a one line content box with block children #then it is a label rather than a card", () => {
+	expect(marked(nestedCards, [outer({ ...inner, rect: { x: 40, y: 40, width: 240, height: 32 }, children: [{ tag: "p", text: "One line of label text" }] })])).toEqual([])
+})
+
+test("#given a declared mockup with three runs #then its nested cards leave the page content", () => {
+	const drawing = { ...outer(inner), attributes: { inert: "" }, children: [{ tag: "p", text: "Preview interface" }, inner] }
+	const page = { tag: "p", text: "Readable page content. ".repeat(40) }
+	expect(marked(nestedCards, [page, drawing])).toEqual([])
+	expect(marked(nestedCards, [page, { ...drawing, attributes: {} }])).toEqual(["#inner"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/layout/nested-cards.ts

@@ -0,0 +1,38 @@
+import { ancestors, descendants, isIgnored, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { cardLike, controlStrip, dialogCard, embeddedFrame, fieldBox, hasBorderOrShadow, labelBox, pageFrame, sharesEdges } from "./support/cards"
+import { hasRole, ident, outOfFlow, painted } from "./support/geometry"
+import { declaredMockups } from "./support/declared-mockups"
+
+export const nestedCards: PageRule = {
+	meta: {
+		id: "nested-cards", name: "Nested cards", category: "slop", severity: "warning", engine: "page",
+		description: "A bordered or raised card sits inside another card and adds an unnecessary surface.",
+		fixHint: "Flatten the inner group with spacing, typography, or a divider instead of another card frame.",
+	},
+	check: ({ snapshot }) => {
+		const mockups = declaredMockups(snapshot)
+		const candidates = snapshot.elements.filter((el) => {
+			if ([el, ...ancestors(snapshot, el)].some((a) => mockups.has(a)) ||
+				!painted(snapshot, el) || !cardLike(snapshot, el) || !hasBorderOrShadow(el) || outOfFlow(el) ||
+				hasRole(el, ["menu", "listbox", "tablist", "radiogroup", "toolbar"]) ||
+				/(?:^|[\s_-])(?:popover|dropdown|tooltip)(?:$|[\s_-])/.test(ident(el)) ||
+				el.text.length < 10 || el.rect.width < 50 || el.rect.height < 30 ||
+				/^(inline|contents)$/.test(styleOf(el, "display")) || labelBox(snapshot, el) || fieldBox(snapshot, el) || controlStrip(snapshot, el)) return false
+			const outer = [...ancestors(snapshot, el)].find((a) => cardLike(snapshot, a) && !pageFrame(snapshot, a))
+			return outer !== undefined && !sharesEdges(snapshot, el, outer) && !dialogCard(snapshot, outer) && !embeddedFrame(snapshot, el, outer)
+		})
+		const panels = new Set<string>()
+		return candidates.filter((el) => ![...descendants(snapshot, el)].some((d) => candidates.includes(d)))
+			.filter((el) => {
+				if (isIgnored(snapshot, el, "nested-cards")) return false
+				const outer = [...ancestors(snapshot, el)].find((a) => cardLike(snapshot, a) && !pageFrame(snapshot, a))
+				const picture = [...ancestors(snapshot, el)].some((a) => a.tag !== "svg" && hasRole(a, ["img"]))
+				const key = `${outer?.index}:${picture}`
+				if (panels.has(key)) return false
+				panels.add(key)
+				return true
+			})
+			.map((el) => ({ element: el, message: "A separately framed card is nested inside another card.", snippet: shortSnippet(el) }))
+	},
+}

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

@@ -0,0 +1,33 @@
+import { expect, test } from "bun:test"
+import { straggler } from "./straggler"
+import { lines, marked } from "./support/layout-cases"
+
+const text = "Line breaks decide how a block of text sits on the page, and one word alone on the last line leaves a hole under the text."
+const paragraph = { id: "copy", tag: "p", text, rect: { x: 24, y: 24, width: 390, height: 96 }, lineRects: lines([390, 390, 350, 50]) }
+
+test("#given a short one word tail and a filled final line #then only the straggler reports", () => {
+	expect(marked(straggler, [paragraph])).toEqual(["#copy"])
+	expect(marked(straggler, [{ ...paragraph, lineRects: lines([390, 390, 350, 250]) }])).toEqual([])
+})
+
+test("#given authored breaks and chosen wrapping #then paragraph wrap is not second guessed", () => {
+	expect(marked(straggler, [paragraph])).toEqual(["#copy"])
+	expect(marked(straggler, [{ ...paragraph, style: { "text-wrap": "pretty" } }])).toEqual([])
+	expect(marked(straggler, [{ ...paragraph, style: { "text-wrap": "balance" } }])).toEqual([])
+	expect(marked(straggler, [{ ...paragraph, children: [{ tag: "br" }] }])).toEqual([])
+})
+
+test("#given narrow columns and inline pictures #then the one face estimate is not applied", () => {
+	expect(marked(straggler, [paragraph])).toEqual(["#copy"])
+	expect(marked(straggler, [{ ...paragraph, text: "Billing settings and invoice history", lineRects: lines([150, 150, 40]) }])).toEqual([])
+	expect(marked(straggler, [{ ...paragraph, children: [{ tag: "img" }] }])).toEqual([])
+})
+
+test("#given lines hidden by a clamp #then the hidden tail is not called a straggler", () => {
+	expect(marked(straggler, [paragraph])).toEqual(["#copy"])
+	expect(marked(straggler, [{ ...paragraph, style: { "overflow-y": "hidden" }, rect: { x: 24, y: 24, width: 390, height: 40 } }])).toEqual([])
+})
+
+test("#given an auto scrolling ancestor #then a reachable last line is still measured", () => {
+	expect(marked(straggler, [{ style: { "overflow-y": "auto" }, rect: { x: 24, y: 24, width: 400, height: 40 }, children: [paragraph] }])).toEqual(["#copy"])
+})

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

@@ -0,0 +1,28 @@
+import { shortSnippet } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { measuredLines, oneFace, wordsOf, wrapIs } from "./support/line-breaks"
+
+export const straggler: PageRule = {
+	meta: {
+		id: "straggler", name: "Straggler", category: "quality", severity: "advisory", engine: "page",
+		description: "A paragraph leaves one short word on its last line.",
+		fixHint: "Use text-wrap: pretty or edit the ending so the last line has company.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap((el) => {
+		if (!["p", "li", "dd", "blockquote", "figcaption"].includes(el.tag) || wrapIs(el, "pretty") || !oneFace(snapshot, el)) return []
+		const lines = measuredLines(snapshot, el)
+		const tail = lines.at(-1)
+		const words = wordsOf(el)
+		const last = words.at(-1)
+		const before = words.at(-2)
+		if (lines.length < 2 || !tail || !last || !before || words.length < 3 ||
+			/[\u3000-\u9fff\uac00-\ud7af]/.test(el.text) || lines.length <= 6 && wrapIs(el, "balance")) return []
+		const widest = Math.max(...lines.map((l) => l.width))
+		const sum = lines.reduce((n, l) => n + l.width, 0)
+		const perPx = el.text.replace(/[\u00ad\u200b]/g, "").length / sum
+		if (tail.width > widest * 0.3 || widest * perPx < 30 || el.text.endsWith(`${before}\u00a0${last}`)) return []
+		const tailChars = tail.width * perPx
+		if (tailChars > last.length + 1.5 || tailChars >= last.length + before.length + 1) return []
+		return [{ element: el, message: `"${last}" appears alone on the last of ${lines.length} lines.`, snippet: shortSnippet(el) }]
+	}),
+}

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

@@ -0,0 +1,114 @@
+import { ancestors, childrenOf, descendants, effectiveBackground, fontSizePx, parentOf, styleOf } from "../../../core/page"
+import { blend, contrastRatio, parseColor, WHITE } from "../../../core/color"
+import { parseShadow } from "../../../core/shadow"
+import type { ElementSnapshot, PageSnapshot } from "../../../types"
+import { borders, bottom, chain, clipsX, clipsY, hasRole, length, lineHeight, painted, right, scrollsX } from "./geometry"
+
+const shadowLayers = (el: ElementSnapshot) => parseShadow(styleOf(el, "box-shadow")).filter((s) => s.color.a >= 0.05)
+export const hasBorderOrShadow = (el: ElementSnapshot): boolean =>
+	borders(el).some(Boolean) || shadowLayers(el).some((s) => s.x !== 0 || s.y !== 0 || s.blur > 0 || s.spread !== 0)
+
+export function fillDiffers(s: PageSnapshot, el: ElementSnapshot): boolean {
+	if (!["none", ""].includes(styleOf(el, "background-image"))) return true
+	const fill = parseColor(styleOf(el, "background-color"))
+	if (!fill || fill.a === 0) return false
+	const p = parentOf(s, el)
+	const under = p ? effectiveBackground(s, p) : WHITE
+	const shown = blend(fill, under)
+	return Math.max(Math.abs(shown.r - under.r), Math.abs(shown.g - under.g), Math.abs(shown.b - under.b)) > 3
+}
+
+export function cardLike(s: PageSnapshot, el: ElementSnapshot): boolean {
+	if (/^(a|button|label|input|select|textarea|img|video|canvas|picture|svg|path|span|code|pre)$/.test(el.tag)) return false
+	const layers = shadowLayers(el)
+	const shadow = layers.some((l) => l.x !== 0 || l.y !== 0 || l.blur > 0 || l.spread !== 0)
+	const rounded = ["top-left", "top-right", "bottom-right", "bottom-left"].some((c) => Number.parseFloat(styleOf(el, `border-${c}-radius`)) > 0)
+	if (!shadow && !rounded) return false
+	const p = parentOf(s, el)
+	const under = p ? effectiveBackground(s, p) : WHITE
+	const ink = parseColor(styleOf(el, "color"))
+	const canJudge = ink !== null && contrastRatio(blend(ink, under), under) >= 3
+	const sides = borders(el).map((visible, i) => {
+		const side = ["top", "right", "bottom", "left"][i] ?? "top"
+		const color = parseColor(styleOf(el, `border-${side}-color`))
+		if (!visible || !canJudge || !color) return visible
+		const edge = blend(color, effectiveBackground(s, el))
+		return Math.max(Math.abs(edge.r - under.r), Math.abs(edge.g - under.g), Math.abs(edge.b - under.b)) >= 8
+	})
+	for (const l of layers.filter((l) => !l.inset)) {
+		const spread = l.spread + l.blur / 2
+		for (const [i, reach] of [spread - l.y, spread + l.x, spread + l.y, spread - l.x].entries()) if (reach >= 1) sides[i] = true
+	}
+	return sides.filter(Boolean).length >= 3 || fillDiffers(s, el)
+}
+
+export function labelBox(s: PageSnapshot, el: ElementSnapshot): boolean {
+	const radius = Number.parseFloat(styleOf(el, "border-top-left-radius"))
+	if (radius >= el.rect.height / 2 - 0.5) return true
+	const kids = childrenOf(s, el)
+	const chrome = ["padding-top", "padding-bottom", "border-top-width", "border-bottom-width"].reduce((n, p) => n + length(el, p), 0)
+	return (kids.length === 0 && el.lineRects.length === 1 && el.rect.height <= lineHeight(el) * 3) ||
+		el.rect.height - chrome <= lineHeight(el) * 1.5
+}
+
+export function embeddedFrame(s: PageSnapshot, el: ElementSnapshot, outer: ElementSnapshot): boolean {
+	const nodes = [...descendants(s, el)].filter((n) => painted(s, n))
+	const controls = nodes.filter((n) => n.tag === "button" || hasRole(n, ["button"]) || n.tag === "input" || n.tag === "select")
+	const realControls = controls.filter((n) => !/copy|more|play|pause|mute|volume|seek|fullscreen|speed/i.test(n.attributes["aria-label"] ?? n.text))
+	if (realControls.length > 0) return false
+	if ([...descendants(s, el)].some((n) => n.tag === "audio") && controls.length > 0 && nodes.some((n) => hasRole(n, ["slider"]))) return true
+	const area = el.rect.width * el.rect.height
+	if (nodes.some((n) => /^(svg|canvas|img|video|iframe|picture)$/.test(n.tag) && n.rect.width * n.rect.height >= area * 0.4) && el.text.length <= 300) return true
+	if (nodes.some((n) => /^(video|audio)$/.test(n.tag) && n.rect.width >= 80) && controls.length > 0) return true
+	if (!/monospace/i.test(styleOf(outer, "font-family"))) {
+		const all = [el, ...nodes]
+		const total = all.reduce((n, c) => n + c.ownText.replace(/\s/g, "").length, 0)
+		const mono = all.filter((n) => /monospace/i.test(styleOf(n, "font-family"))).reduce((n, c) => n + c.ownText.replace(/\s/g, "").length, 0)
+		if (total > 0 && mono / total >= 0.9 && all.some((n) => /^(pre|code|samp|kbd|output)$/.test(n.tag) || n.ownText.length >= el.text.length * 0.6 || /const |await |=>|[{};]/.test(n.text))) return true
+	}
+	return false
+}
+
+export function fieldBox(s: PageSnapshot, el: ElementSnapshot): boolean {
+	const kids = childrenOf(s, el).filter((c) => painted(s, c))
+	const field = (c: ElementSnapshot): boolean => /^(input|textarea|select)$/.test(c.tag) || c.attributes["contenteditable"] === "true"
+	return kids.some(field) && kids.every((c) => field(c) || c.text.length <= 20 && [c, ...descendants(s, c)].some((n) => n.tag === "button"))
+}
+
+export function sharesEdges(s: PageSnapshot, el: ElementSnapshot, outer: ElementSnapshot): boolean {
+	const a = el.rect
+	const b = outer.rect
+	const edges = [
+		Math.abs(a.y - b.y - length(outer, "border-top-width")) <= 1.5,
+		Math.abs(right(a) - right(b) + length(outer, "border-right-width")) <= 1.5,
+		Math.abs(bottom(a) - bottom(b) + length(outer, "border-bottom-width")) <= 1.5,
+		Math.abs(a.x - b.x - length(outer, "border-left-width")) <= 1.5,
+	]
+	if (edges.filter(Boolean).length >= 3) return true
+	if (!((edges[0] || edges[2]) && (edges[1] || edges[3]))) return false
+	return [...ancestors(s, el)].some((c) => (clipsX(c) || clipsY(c)) &&
+		((Math.abs(a.width - c.rect.width) <= 1.5 && c.rect.height > a.height + 1.5) ||
+			(Math.abs(a.height - c.rect.height) <= 1.5 && c.rect.width > a.width + 1.5)))
+}
+
+export function controlStrip(s: PageSnapshot, el: ElementSnapshot): boolean {
+	const p = parentOf(s, el)
+	if (p && scrollsX(p)) return true
+	const kids = childrenOf(s, el)
+	const first = kids[0]
+	return first !== undefined && kids.length >= 3 && kids.every((c) =>
+		(c.tag === "a" || c.tag === "button" || hasRole(c, ["link", "button", "tab"])) && c.rect.height <= 64 &&
+		Math.min(bottom(c.rect), bottom(first.rect)) - Math.max(c.rect.y, first.rect.y) > Math.min(c.rect.height, first.rect.height) * 0.5)
+}
+
+export function dialogCard(s: PageSnapshot, el: ElementSnapshot): boolean {
+	for (const a of chain(s, el)) {
+		if (a.tag === "dialog" || hasRole(a, ["dialog", "alertdialog"])) return true
+		if (a !== el && cardLike(s, a)) return false
+	}
+	return false
+}
+
+export const pageFrame = (s: PageSnapshot, el: ElementSnapshot): boolean =>
+	el.rect.x <= 1 && el.rect.width >= s.document.clientWidth - 1 && el.rect.height >= s.document.scrollHeight * 0.75 &&
+	!borders(el).some(Boolean) && !fillDiffers(s, el) && shadowLayers(el).every((l) => l.color.a <= 0.05)