lazycodex-ai 5.1.48 → 5.1.54

package/packages/shared-skills/skills/frontend/scripts/detect/core/page.ts

@@ -0,0 +1,84 @@
+import type { ElementSnapshot, PageSnapshot } from "../types"
+import { blend, parseColor, type Rgba, WHITE } from "./color"
+
+export const IGNORE_ATTRIBUTES = ["data-detect-ignore", "data-impeccable-ignore"] as const
+
+/** Numeric value of a computed length in px ("12px" -> 12, "normal"/"auto" -> null). */
+export function px(value: string | undefined): number | null {
+	if (value === undefined) return null
+	const m = /^(-?\d*\.?\d+)px$/.exec(value.trim())
+	return m?.[1] === undefined ? null : Number.parseFloat(m[1])
+}
+
+export const styleOf = (el: ElementSnapshot, prop: string): string => el.style[prop] ?? ""
+
+export function parentOf(snap: PageSnapshot, el: ElementSnapshot): ElementSnapshot | null {
+	return el.parent === null ? null : (snap.elements[el.parent] ?? null)
+}
+
+export function* ancestors(snap: PageSnapshot, el: ElementSnapshot): Generator<ElementSnapshot> {
+	let cur = parentOf(snap, el)
+	while (cur) {
+		yield cur
+		cur = parentOf(snap, cur)
+	}
+}
+
+export function* descendants(snap: PageSnapshot, el: ElementSnapshot): Generator<ElementSnapshot> {
+	for (const i of el.children) {
+		const child = snap.elements[i]
+		if (!child) continue
+		yield child
+		yield* descendants(snap, child)
+	}
+}
+
+export const childrenOf = (snap: PageSnapshot, el: ElementSnapshot): readonly ElementSnapshot[] =>
+	el.children.map((i) => snap.elements[i]).filter((c): c is ElementSnapshot => c !== undefined)
+
+/** Rendered and not visually suppressed: has a box, is not display:none/visibility:hidden, and no ancestor has opacity 0. */
+export function isRendered(snap: PageSnapshot, el: ElementSnapshot): boolean {
+	if (el.rect.width <= 0 || el.rect.height <= 0) return false
+	if (styleOf(el, "display") === "none" || styleOf(el, "visibility") === "hidden") return false
+	if (Number.parseFloat(styleOf(el, "opacity")) === 0) return false
+	for (const a of ancestors(snap, el)) if (Number.parseFloat(styleOf(a, "opacity")) === 0) return false
+	return true
+}
+
+/** True when the element or an ancestor waives `ruleId` with data-detect-ignore (or upstream's data-impeccable-ignore). */
+export function isIgnored(snap: PageSnapshot, el: ElementSnapshot, ruleId: string): boolean {
+	const waives = (e: ElementSnapshot): boolean =>
+		IGNORE_ATTRIBUTES.some((name) => {
+			const v = e.attributes[name]
+			if (v === undefined) return false
+			const ids = v.split(/[\s,]+/).filter(Boolean)
+			return ids.length === 0 || ids.includes(ruleId) || ids.includes("all")
+		})
+	if (waives(el)) return true
+	for (const a of ancestors(snap, el)) if (waives(a)) return true
+	return false
+}
+
+/** The opaque color painted behind `el`: its own and its ancestors' background-colors composited bottom-up over white. */
+export function effectiveBackground(snap: PageSnapshot, el: ElementSnapshot): Rgba {
+	const layers: Rgba[] = []
+	for (const e of [el, ...ancestors(snap, el)]) {
+		const c = parseColor(styleOf(e, "background-color"))
+		if (c && c.a > 0) {
+			layers.push(c)
+			if (c.a >= 1) break
+		}
+	}
+	return layers.reduceRight<Rgba>((under, top) => blend(top, under), WHITE)
+}
+
+const HEADING_TAGS = ["h1", "h2", "h3", "h4", "h5", "h6"] as const
+export const isHeading = (el: ElementSnapshot): boolean => HEADING_TAGS.some((tag) => tag === el.tag)
+export const headingLevel = (el: ElementSnapshot): number | null => (isHeading(el) ? Number(el.tag.slice(1)) : null)
+
+export const textElements = (snap: PageSnapshot): readonly ElementSnapshot[] =>
+	snap.elements.filter((el) => el.ownText !== "" && isRendered(snap, el))
+
+export const fontSizePx = (el: ElementSnapshot): number => px(styleOf(el, "font-size")) ?? 16
+
+export const shortSnippet = (el: ElementSnapshot): string => (el.text === "" ? `<${el.tag}>` : `<${el.tag}> ${el.text.slice(0, 80)}`)

package/packages/shared-skills/skills/frontend/scripts/detect/core/shadow.ts

@@ -0,0 +1,40 @@
+import { parseColor, type Rgba } from "./color"
+
+export type ShadowLayer = {
+	readonly inset: boolean
+	readonly color: Rgba
+	readonly x: number
+	readonly y: number
+	readonly blur: number
+	readonly spread: number
+}
+
+function splitLayers(value: string): readonly string[] {
+	const layers: string[] = []
+	let depth = 0
+	let start = 0
+	for (let i = 0; i < value.length; i++) {
+		const ch = value[i]
+		if (ch === "(") depth++
+		else if (ch === ")") depth--
+		else if (ch === "," && depth === 0) {
+			layers.push(value.slice(start, i).trim())
+			start = i + 1
+		}
+	}
+	layers.push(value.slice(start).trim())
+	return layers.filter(Boolean)
+}
+
+/** Parses a computed box-shadow or text-shadow value into layers; `none` yields no layers. */
+export function parseShadow(value: string): readonly ShadowLayer[] {
+	if (value.trim() === "" || value.trim() === "none") return []
+	return splitLayers(value).flatMap((layer) => {
+		const colorMatch = /(rgba?|color|oklab|oklch)\([^()]*\)|#[0-9a-f]{3,8}\b|\btransparent\b/i.exec(layer)
+		const color = (colorMatch ? parseColor(colorMatch[0]) : null) ?? { r: 0, g: 0, b: 0, a: 1 }
+		const rest = colorMatch ? layer.replace(colorMatch[0], " ") : layer
+		const lengths = [...rest.matchAll(/(-?\d*\.?\d+)(px)?(?=\s|$)/g)].map((m) => Number.parseFloat(m[1] ?? "0"))
+		if (lengths.length < 2) return []
+		return [{ inset: /\binset\b/.test(rest), color, x: lengths[0] ?? 0, y: lengths[1] ?? 0, blur: lengths[2] ?? 0, spread: lengths[3] ?? 0 }]
+	})
+}

package/packages/shared-skills/skills/frontend/scripts/detect/core/source.ts

@@ -0,0 +1,33 @@
+import type { SourceHit } from "../rule"
+
+export const extensionOf = (path: string): string => (/\.([a-z0-9]+)$/i.exec(path)?.[1] ?? "").toLowerCase()
+
+/** 1-based line and column of a string offset. */
+export function positionAt(text: string, offset: number): { readonly line: number; readonly column: number } {
+	let line = 1
+	let lineStart = 0
+	for (let i = 0; i < offset && i < text.length; i++) {
+		if (text.charCodeAt(i) === 10) {
+			line++
+			lineStart = i + 1
+		}
+	}
+	return { line, column: offset - lineStart + 1 }
+}
+
+export function lineAt(text: string, offset: number): string {
+	const start = text.lastIndexOf("\n", offset - 1) + 1
+	const end = text.indexOf("\n", offset)
+	return text.slice(start, end === -1 ? text.length : end).trim().slice(0, 160)
+}
+
+/** CSS declaration blocks of a stylesheet-like text: selector plus raw body, with the body's start offset. */
+export function cssBlocks(text: string): readonly { readonly selector: string; readonly body: string; readonly offset: number }[] {
+	const stripped = text.replace(/\/\*[\s\S]*?\*\//g, (c) => " ".repeat(c.length))
+	const out: { selector: string; body: string; offset: number }[] = []
+	for (const m of stripped.matchAll(/([^{};]+)\{([^{}]*)\}/g)) {
+		if (m.index === undefined) continue
+		out.push({ selector: (m[1] ?? "").trim(), body: m[2] ?? "", offset: m.index + (m[1] ?? "").length + 1 })
+	}
+	return out
+}

package/packages/shared-skills/skills/frontend/scripts/detect/detect.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { extensionOf } from "./core/source"
+import { lintSnapshot, lintSources, sortFindings, type LintOptions } from "./lint"
+import type { RenderTarget, Renderer } from "./render/renderer"
+import { createWebViewRenderer } from "./render/webview"
+import type { DetectConfig, Finding, Viewport } from "./types"
+
+/** @public */
+export const DEFAULT_VIEWPORTS: readonly Viewport[] = [
+	{ width: 1440, height: 900 },
+	{ width: 390, height: 844 },
+]
+
+/** StyleGallery's reflow matrix: every width, with an unbroken stress token added at the narrowest one. @public */
+export const REFLOW_VIEWPORTS: readonly Viewport[] = [320, 375, 768, 1024, 1440].map((width) => ({ width, height: 800 }))
+
+export type DetectPageOptions = LintOptions & {
+	readonly viewports?: readonly Viewport[]
+	/** Bring your own renderer (Playwright, omowright); defaults to a Bun.WebView renderer created and closed here. */
+	readonly renderer?: Renderer
+	/** Also render at REFLOW_VIEWPORTS with content stress at 320 px, feeding the viewport-reflow rule. */
+	readonly reflow?: boolean
+}
+
+const PAGE_EXTENSIONS = new Set(["html", "htm"])
+
+/** Renders a page at each viewport and lints every snapshot. */
+export async function detectPage(target: RenderTarget, options: DetectPageOptions = {}): Promise<readonly Finding[]> {
+	const renderer = options.renderer ?? createWebViewRenderer()
+	try {
+		const findings: Finding[] = []
+		const passes = [
+			...(options.viewports ?? DEFAULT_VIEWPORTS).map((viewport) => ({ viewport, contentStress: false })),
+			...(options.reflow ? REFLOW_VIEWPORTS.map((viewport) => ({ viewport, contentStress: viewport.width === 320 })) : []),
+		]
+		for (const pass of passes) {
+			const snapshot = await renderer.render({ target, ...pass })
+			findings.push(...lintSnapshot(snapshot, options))
+		}
+		return sortFindings(dedupe(findings))
+	} finally {
+		if (!options.renderer) await renderer.close()
+	}
+}
+
+/** Lints files: HTML is rendered and checked as a page, everything else is checked as source text. */
+export async function detectFiles(paths: readonly string[], options: DetectPageOptions = {}): Promise<readonly Finding[]> {
+	const pages = paths.filter((p) => PAGE_EXTENSIONS.has(extensionOf(p)))
+	const sources = paths.filter((p) => !PAGE_EXTENSIONS.has(extensionOf(p)))
+	const findings: Finding[] = [...lintSources(sources.map((path) => ({ path, text: readFileSync(path, "utf8") })), options)]
+	const renderer = options.renderer ?? createWebViewRenderer()
+	try {
+		for (const page of pages) {
+			const url = pathToFileURL(resolve(page)).href
+			findings.push(...(await detectPage({ kind: "url", url }, { ...options, renderer, file: page })))
+		}
+	} finally {
+		if (!options.renderer) await renderer.close()
+	}
+	return sortFindings(findings)
+}
+
+/** The same rule on the same element at two viewports is one finding; the first viewport's location is kept. */
+function dedupe(findings: readonly Finding[]): readonly Finding[] {
+	const seen = new Set<string>()
+	return findings.filter((f) => {
+		const where = f.location.kind === "element" ? f.location.selector : f.location.kind === "source" ? `${f.location.line}:${f.location.column}` : "page"
+		const key = `${f.ruleId}|${where}|${f.message}`
+		if (seen.has(key)) return false
+		seen.add(key)
+		return true
+	})
+}
+
+export type { DetectConfig }

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

@@ -0,0 +1,23 @@
+/** The frontend detect SDK's public API: everything below is for callers outside this repository (a skill script, a project's own lint step). */
+/** @public */
+export { blend, colorsIn, contrastRatio, luminance, parseColor, type Rgba } from "./core/color"
+/** @public */
+export { parseConfig } from "./config"
+/** @public */
+export { DEFAULT_VIEWPORTS, detectFiles, detectPage, type DetectPageOptions, REFLOW_VIEWPORTS } from "./detect"
+/** @public */
+export { effectiveSeverity, hasFailures, type LintOptions, lintSnapshot, lintSources, sortFindings } from "./lint"
+/** @public */
+export { formatFindingsText, summarize } from "./report"
+/** @public */
+export { RenderError, type RenderRequest, type RenderTarget, type Renderer } from "./render/renderer"
+/** @public */
+export { createWebViewRenderer } from "./render/webview"
+export type { PageContext, PageHit, PageRule, Rule, SourceContext, SourceHit, SourceRule } from "./rule"
+/** @public */
+export { ALL_RULES } from "./rules"
+/** @public */
+export { collectPageSnapshot } from "./snapshot/collect"
+/** @public */
+export { STYLE_PROPS } from "./snapshot/style-props"
+export type * from "./types"

package/packages/shared-skills/skills/frontend/scripts/detect/lint.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test"
+import { lintSnapshot } from "./lint"
+import type { PageRule } from "./rule"
+import { buildSnapshot } from "./testing/build-snapshot"
+
+const twoHits: PageRule = {
+	meta: { id: "two-hits", name: "Two hits", category: "quality", severity: "error", engine: "page", description: "d", fixHint: "f" },
+	check: () => [
+		{ element: null, message: "default", snippet: "" },
+		{ element: null, message: "softer", snippet: "", severity: "advisory" },
+	],
+}
+
+describe("lintSnapshot severity", () => {
+	test("#given a hit with its own severity #then it replaces the rule default for that hit only", () => {
+		const findings = lintSnapshot(buildSnapshot([]), { rules: [twoHits] })
+		expect(findings.map((f) => [f.message, f.severity])).toEqual([
+			["default", "error"],
+			["softer", "advisory"],
+		])
+	})
+
+	test("#given a project override for the rule #then every hit takes the override", () => {
+		const findings = lintSnapshot(buildSnapshot([]), { rules: [twoHits], config: { rules: { "two-hits": "warning" } } })
+		expect(findings.map((f) => f.severity)).toEqual(["warning", "warning"])
+	})
+})

package/packages/shared-skills/skills/frontend/scripts/detect/lint.ts

@@ -0,0 +1,98 @@
+import { isIgnored } from "./core/page"
+import { extensionOf } from "./core/source"
+import type { PageRule, Rule, SourceRule } from "./rule"
+import { ALL_RULES } from "./rules"
+import type { DetectConfig, Finding, PageSnapshot, RuleMeta, Severity, SourceFile } from "./types"
+
+export type LintOptions = {
+	readonly config?: DetectConfig
+	/** Rules to run; defaults to every built-in rule. */
+	readonly rules?: readonly Rule[]
+	/** File the snapshot was rendered from, carried into element locations. */
+	readonly file?: string
+}
+
+/** Severity after the project's override, or null when the rule is switched off. @public */
+export function effectiveSeverity(meta: RuleMeta, config: DetectConfig | undefined): Severity | null {
+	const setting = config?.rules?.[meta.id]
+	if (setting === "off") return null
+	return setting ?? meta.severity
+}
+
+const isPageRule = (r: Rule): r is PageRule => r.meta.engine === "page"
+const isSourceRule = (r: Rule): r is SourceRule => r.meta.engine === "source"
+
+export function lintSnapshot(snapshot: PageSnapshot, options: LintOptions = {}): readonly Finding[] {
+	const config = options.config ?? {}
+	const findings: Finding[] = []
+	for (const rule of (options.rules ?? ALL_RULES).filter(isPageRule)) {
+		const severity = effectiveSeverity(rule.meta, config)
+		if (severity === null) continue
+		const overridden = config.rules?.[rule.meta.id] !== undefined
+		for (const hit of rule.check({ snapshot, config })) {
+			if (hit.element && isIgnored(snapshot, hit.element, rule.meta.id)) continue
+			findings.push({
+				ruleId: rule.meta.id,
+				name: rule.meta.name,
+				category: rule.meta.category,
+				severity: hit.severityFixed && hit.severity ? hit.severity : overridden ? severity : (hit.severity ?? severity),
+				message: hit.message,
+				fixHint: rule.meta.fixHint,
+				snippet: hit.snippet,
+				location: hit.element
+					? { kind: "element", selector: hit.element.selector, rect: hit.element.rect, viewport: snapshot.viewport, ...(options.file ? { file: options.file } : {}) }
+					: { kind: "page", viewport: snapshot.viewport, ...(options.file ? { file: options.file } : {}) },
+			})
+		}
+	}
+	return findings
+}
+
+export function lintSources(files: readonly SourceFile[], options: LintOptions = {}): readonly Finding[] {
+	const config = options.config ?? {}
+	const findings: Finding[] = []
+	const rules = (options.rules ?? ALL_RULES).filter(isSourceRule)
+	for (const file of files) {
+		const ext = extensionOf(file.path)
+		for (const rule of rules) {
+			if (!rule.extensions.includes(ext)) continue
+			const severity = effectiveSeverity(rule.meta, config)
+			if (severity === null) continue
+			for (const hit of rule.check({ file, config })) {
+				findings.push({
+					ruleId: rule.meta.id,
+					name: rule.meta.name,
+					category: rule.meta.category,
+					severity,
+					message: hit.message,
+					fixHint: rule.meta.fixHint,
+					snippet: hit.snippet,
+					location: { kind: "source", file: file.path, line: hit.line, column: hit.column },
+				})
+			}
+		}
+	}
+	return findings
+}
+
+const SEVERITY_ORDER: Readonly<Record<Severity, number>> = { error: 0, warning: 1, advisory: 2 }
+
+export function sortFindings(findings: readonly Finding[]): readonly Finding[] {
+	const key = (f: Finding): string => {
+		const l = f.location
+		switch (l.kind) {
+			case "source":
+				return `${l.file}:${String(l.line).padStart(8, "0")}:${String(l.column).padStart(6, "0")}`
+			case "element":
+				return `${l.file ?? ""}@${l.viewport.width}:${String(Math.round(l.rect.y)).padStart(8, "0")}:${l.selector}`
+			case "page":
+				return `${l.file ?? ""}@${l.viewport.width}`
+		}
+	}
+	return [...findings].sort(
+		(a, b) => key(a).localeCompare(key(b)) || SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || a.ruleId.localeCompare(b.ruleId),
+	)
+}
+
+/** True when any finding is an error or a warning; advisories never fail a gate. */
+export const hasFailures = (findings: readonly Finding[]): boolean => findings.some((f) => f.severity !== "advisory")

package/packages/shared-skills/skills/frontend/scripts/detect/render/probe-placement.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test"
+import { insertAfterProlog } from "./probe-placement"
+
+const P = "<script>probe</script>"
+
+test.each([
+	["a head", "<!doctype html><html><head><title>t</title></head>", `<!doctype html><html><head>${P}<title>t</title></head>`],
+	["no head", "<!doctype html><html lang=en><body><p>x</p>", `<!doctype html><html lang=en>${P}<body><p>x</p>`],
+	["only a doctype", "<!DOCTYPE html><header>h</header>", `<!DOCTYPE html>${P}<header>h</header>`],
+	["no prolog", "<header>h</header><p>x</p>", `${P}<header>h</header><p>x</p>`],
+	["a <head> inside a leading comment", "<!-- <head> --><!doctype html><p>x</p>", `<!-- <head> --><!doctype html>${P}<p>x</p>`],
+	["a <head> inside a later script string", "<!doctype html><body><script>var s = \"<head>\"</script>", `<!doctype html>${P}<body><script>var s = \"<head>\"</script>`],
+	["a > inside a quoted attribute", '<!doctype html><html><head data-x="a>b"><title>t</title>', `<!doctype html><html><head data-x="a>b">${P}<title>t</title>`],
+	["a <header> where the head would be", "<html><header>h</header>", `<html>${P}<header>h</header>`],
+	["a leading XML declaration", '<?xml version="1.0"?>\n<!DOCTYPE html><html><head>', `<?xml version="1.0"?>\n<!DOCTYPE html><html><head>${P}`],
+	["comments and whitespace between prolog tags", "<!doctype html>\n<!-- c -->\n<html>\n<head>", `<!doctype html>\n<!-- c -->\n<html>\n<head>${P}`],
+])("#given %s #then the probe lands right after the prolog", (_name, html, expected) => {
+	expect(insertAfterProlog(html, P)).toBe(expected)
+})

package/packages/shared-skills/skills/frontend/scripts/detect/render/probe-placement.ts

@@ -0,0 +1,50 @@
+const PROLOG_TAGS = ["!doctype", "html", "head"] as const
+
+function skipBlankAndComments(html: string, from: number): number {
+	let i = from
+	for (;;) {
+		while (i < html.length && /\s/.test(html.charAt(i))) i++
+		const [open, close] = html.startsWith("<!--", i) ? ["<!--", "-->"] : html.startsWith("<?", i) ? ["<?", "?>"] : ["", ""]
+		if (open === "") return i
+		const end = html.indexOf(close, i + open.length)
+		if (end === -1) return html.length
+		i = end + close.length
+	}
+}
+
+function tagEnd(html: string, from: number): number {
+	let quote = ""
+	for (let i = from; i < html.length; i++) {
+		const c = html.charAt(i)
+		if (quote !== "") {
+			if (c === quote) quote = ""
+		} else if (c === '"' || c === "'") quote = c
+		else if (c === ">") return i + 1
+	}
+	return -1
+}
+
+function openingAt(html: string, at: number, name: string): boolean {
+	if (html.charAt(at) !== "<" || html.slice(at + 1, at + 1 + name.length).toLowerCase() !== name) return false
+	const next = html.charAt(at + 1 + name.length)
+	return next === ">" || next === "/" || /\s/.test(next)
+}
+
+/**
+ * Inserts `snippet` right after the document prolog (doctype, then the `<html>` and `<head>` openings, in that order,
+ * with whitespace, comments and processing instructions such as `<?xml ...?>` between them), so it runs before any page script and never lands before the doctype,
+ * inside a comment, inside an attribute value, or inside a later script. With no prolog it goes first.
+ */
+export function insertAfterProlog(html: string, snippet: string): string {
+	let at = 0
+	let next = 0
+	for (const name of PROLOG_TAGS) {
+		const start = skipBlankAndComments(html, next)
+		if (!openingAt(html, start, name)) continue
+		const end = tagEnd(html, start + 1 + name.length)
+		if (end === -1) break
+		at = end
+		next = end
+	}
+	return `${html.slice(0, at)}${snippet}${html.slice(at)}`
+}

package/packages/shared-skills/skills/frontend/scripts/detect/render/renderer.ts

@@ -0,0 +1,37 @@
+import type { PageSnapshot, Viewport } from "../types"
+
+export type RenderTarget = { readonly kind: "html"; readonly html: string } | { readonly kind: "url"; readonly url: string }
+
+export type RenderRequest = {
+	readonly target: RenderTarget
+	readonly viewport: Viewport
+	/** Appends an unbroken 300-character token to every element whose last child is text, to expose reflow breaks. */
+	readonly contentStress?: boolean
+}
+
+/** Anything that can turn a page into a PageSnapshot: Bun.WebView by default, or a Playwright/omowright page you already drive. */
+export type Renderer = {
+	readonly render: (request: RenderRequest) => Promise<PageSnapshot>
+	readonly close: () => Promise<void>
+}
+
+export class RenderError extends Error {
+	readonly target: string
+	constructor(target: string, cause: unknown) {
+		super(`render failed for ${target}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause })
+		this.name = "RenderError"
+		this.target = target
+	}
+}
+
+const STRESS_TOKEN = "Unbrokencontentstresstoken".repeat(12)
+
+export const CONTENT_STRESS_SCRIPT = `(() => {
+	const token = ${JSON.stringify(STRESS_TOKEN)};
+	for (const el of document.querySelectorAll("body *")) {
+		const last = el.lastChild;
+		if (!last || last.nodeType !== 3 || last.textContent.trim() === "") continue;
+		if (["SCRIPT", "STYLE", "TEXTAREA", "OPTION", "TITLE"].includes(el.tagName)) continue;
+		last.textContent = last.textContent + " " + token;
+	}
+})();`

package/packages/shared-skills/skills/frontend/scripts/detect/render/webview.ts

@@ -0,0 +1,71 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { collectPageSnapshot, SCRIPT_ERROR_PROBE } from "../snapshot/collect"
+import { STYLE_PROPS } from "../snapshot/style-props"
+import type { PageSnapshot } from "../types"
+import { insertAfterProlog } from "./probe-placement"
+import { CONTENT_STRESS_SCRIPT, RenderError, type RenderRequest, type RenderTarget, type Renderer } from "./renderer"
+
+const MAX_ELEMENTS = 20_000
+const SETTLE_FRAMES = "new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => requestAnimationFrame(() => resolve(true)))))"
+
+function withProbe(html: string, baseHref?: string): string {
+	return insertAfterProlog(html, `${baseHref ? `<base href="${baseHref}">` : ""}<script>${SCRIPT_ERROR_PROBE}</script>`)
+}
+
+function isSnapshot(value: unknown): value is PageSnapshot {
+	return typeof value === "object" && value !== null && Array.isArray(Reflect.get(value, "elements"))
+}
+
+/** A renderer backed by Bun.WebView (system WebKit on macOS, installed Chrome/Chromium elsewhere). One view per request. */
+export function createWebViewRenderer(options: { readonly backend?: "webkit" | "chrome" } = {}): Renderer {
+	const scratch = mkdtempSync(join(tmpdir(), "frontend-detect-"))
+	let counter = 0
+	const chrome = options.backend === "chrome" || (options.backend === undefined && process.platform !== "darwin")
+	const writePage = (html: string, baseHref?: string): string => {
+		const file = join(scratch, `page-${counter++}.html`)
+		writeFileSync(file, withProbe(html, baseHref))
+		return pathToFileURL(file).href
+	}
+	const open = async (view: Bun.WebView, target: RenderTarget): Promise<void> => {
+		if (target.kind === "html") return view.navigate(writePage(target.html))
+		if (chrome) {
+			await view.navigate("about:blank")
+			await view.cdp("Page.addScriptToEvaluateOnNewDocument", { source: SCRIPT_ERROR_PROBE })
+			return view.navigate(target.url)
+		}
+		if (target.url.startsWith("file:")) {
+			const path = fileURLToPath(target.url)
+			return view.navigate(writePage(readFileSync(path, "utf8"), pathToFileURL(`${dirname(path)}/`).href))
+		}
+		return view.navigate(target.url)
+	}
+	return {
+		async render(request: RenderRequest): Promise<PageSnapshot> {
+			const label = request.target.kind === "url" ? request.target.url : "inline html"
+			const view = new Bun.WebView({
+				width: request.viewport.width,
+				height: request.viewport.height,
+				...(options.backend ? { backend: options.backend } : {}),
+			})
+			try {
+				await open(view, request.target)
+				await view.evaluate("document.fonts ? document.fonts.ready.then(() => true) : true")
+				await view.evaluate(SETTLE_FRAMES)
+				if (request.contentStress) await view.evaluate(CONTENT_STRESS_SCRIPT)
+				const snapshot: unknown = await view.evaluate(`(${collectPageSnapshot.toString()})(${JSON.stringify(STYLE_PROPS)}, ${MAX_ELEMENTS})`)
+				if (!isSnapshot(snapshot)) throw new Error("the page did not return a snapshot")
+				return snapshot
+			} catch (error) {
+				throw new RenderError(label, error)
+			} finally {
+				await view.close()
+			}
+		},
+		async close(): Promise<void> {
+			rmSync(scratch, { recursive: true, force: true })
+		},
+	}
+}

package/packages/shared-skills/skills/frontend/scripts/detect/report.ts

@@ -0,0 +1,29 @@
+import type { Finding, Severity } from "./types"
+
+/** @public */
+export function summarize(findings: readonly Finding[]): Readonly<Record<Severity, number>> {
+	const counts: Record<Severity, number> = { error: 0, warning: 0, advisory: 0 }
+	for (const f of findings) counts[f.severity]++
+	return counts
+}
+
+function where(f: Finding): string {
+	const l = f.location
+	switch (l.kind) {
+		case "source":
+			return `${l.file}:${l.line}:${l.column}`
+		case "element":
+			return `${l.file ?? "page"} @${l.viewport.width}px ${l.selector}`
+		case "page":
+			return `${l.file ?? "page"} @${l.viewport.width}px`
+	}
+}
+
+export function formatFindingsText(findings: readonly Finding[]): string {
+	const lines = findings.map(
+		(f) => `${where(f)}  ${f.severity}  ${f.ruleId}  ${f.message}\n    > ${f.snippet}\n    fix: ${f.fixHint}`,
+	)
+	const c = summarize(findings)
+	lines.push(`frontend-detect: ${findings.length} finding(s): ${c.error} error, ${c.warning} warning, ${c.advisory} advisory`)
+	return `${lines.join("\n")}\n`
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rule.ts

@@ -0,0 +1,42 @@
+import type { DetectConfig, ElementSnapshot, PageSnapshot, RuleMeta, Severity, SourceFile } from "./types"
+
+export type PageHit = {
+	readonly element: ElementSnapshot | null
+	readonly message: string
+	readonly snippet: string
+	/** Overrides the rule's default severity for this hit; a project override in config.rules still wins. */
+	readonly severity?: Severity
+	/** Keeps `severity` even when the project overrides the rule's severity in config.rules (a rule set to "off" still drops the hit). For notices about missing evidence, which an override must not turn into a failure. */
+	readonly severityFixed?: boolean
+}
+
+export type PageContext = {
+	readonly snapshot: PageSnapshot
+	readonly config: DetectConfig
+}
+
+export type PageRule = {
+	readonly meta: RuleMeta & { readonly engine: "page" }
+	readonly check: (ctx: PageContext) => readonly PageHit[]
+}
+
+export type SourceHit = {
+	readonly line: number
+	readonly column: number
+	readonly message: string
+	readonly snippet: string
+}
+
+export type SourceContext = {
+	readonly file: SourceFile
+	readonly config: DetectConfig
+}
+
+export type SourceRule = {
+	readonly meta: RuleMeta & { readonly engine: "source" }
+	/** File extensions (without the dot) this rule reads, e.g. ["css", "scss", "tsx"]. */
+	readonly extensions: readonly string[]
+	readonly check: (ctx: SourceContext) => readonly SourceHit[]
+}
+
+export type Rule = PageRule | SourceRule