oh-my-opencode 5.1.51 → 5.1.55

package/dist/skills/frontend/scripts/detect/core/color.ts

@@ -0,0 +1,150 @@
+export type Rgba = { readonly r: number; readonly g: number; readonly b: number; readonly a: number }
+
+export const TRANSPARENT: Rgba = { r: 0, g: 0, b: 0, a: 0 }
+export const WHITE: Rgba = { r: 255, g: 255, b: 255, a: 1 }
+
+const clamp255 = (n: number): number => Math.max(0, Math.min(255, n))
+
+function parseHex(hex: string): Rgba | null {
+	const h = hex.slice(1)
+	const full = h.length === 3 || h.length === 4 ? [...h].map((c) => c + c).join("") : h
+	if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(full)) return null
+	const n = (i: number): number => Number.parseInt(full.slice(i, i + 2), 16)
+	return { r: n(0), g: n(2), b: n(4), a: full.length === 8 ? n(6) / 255 : 1 }
+}
+
+function channel(token: string, scale: number): number {
+	return token.endsWith("%") ? (Number.parseFloat(token) / 100) * scale : Number.parseFloat(token)
+}
+
+function oklabToRgb(l: number, a: number, b: number): readonly [number, number, number] {
+	const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3
+	const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3
+	const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3
+	const lin = [
+		4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_,
+		-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_,
+		-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_,
+	] as const
+	const gamma = (c: number): number => clamp255(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055))
+	return [gamma(lin[0]), gamma(lin[1]), gamma(lin[2])]
+}
+
+type Vec3 = readonly [number, number, number]
+const mul = (m: readonly Vec3[], v: Vec3): Vec3 => {
+	const row = (i: number): Vec3 => m[i] ?? [0, 0, 0]
+	const dot = (r: Vec3): number => r[0] * v[0] + r[1] * v[1] + r[2] * v[2]
+	return [dot(row(0)), dot(row(1)), dot(row(2))]
+}
+const XYZ_D65_TO_LINEAR_SRGB: readonly Vec3[] = [
+	[3.2409699419, -1.5373831776, -0.4986107603],
+	[-0.9692436363, 1.8759675015, 0.0415550574],
+	[0.0556300797, -0.2039769589, 1.0569715142],
+]
+const LINEAR_P3_TO_XYZ_D65: readonly Vec3[] = [
+	[0.4865709486, 0.2656676932, 0.1982172852],
+	[0.2289745641, 0.6917385218, 0.0792869141],
+	[0, 0.0451133819, 1.0439443689],
+]
+const XYZ_D50_TO_D65: readonly Vec3[] = [
+	[0.9554734528, -0.0230985368, 0.0632593086],
+	[-0.0283697094, 1.0099954580, 0.0210413990],
+	[0.0123140016, -0.0205076964, 1.3303659366],
+]
+const toLinear = (c: number): number => (Math.abs(c) <= 0.04045 ? c / 12.92 : Math.sign(c) * ((Math.abs(c) + 0.055) / 1.055) ** 2.4)
+const encode = (lin: Vec3): Vec3 => {
+	const gamma = (c: number): number => clamp255(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055))
+	return [gamma(lin[0]), gamma(lin[1]), gamma(lin[2])]
+}
+
+function labToRgb(l: number, a: number, b: number): Vec3 {
+	const fy = (l + 16) / 116
+	const [fx, fz] = [fy + a / 500, fy - b / 200]
+	const inv = (t: number): number => (t ** 3 > 216 / 24389 ? t ** 3 : (116 * t - 16) / (24389 / 27))
+	const xyzD50: Vec3 = [0.3457 / 0.3585 * inv(fx), l > 8 ? fy ** 3 : l / (24389 / 27), (1 - 0.3457 - 0.3585) / 0.3585 * inv(fz)]
+	return encode(mul(XYZ_D65_TO_LINEAR_SRGB, mul(XYZ_D50_TO_D65, xyzD50)))
+}
+
+function predefinedToRgb(space: string, c: Vec3): Vec3 | null {
+	if (space === "srgb") return [clamp255(c[0] * 255), clamp255(c[1] * 255), clamp255(c[2] * 255)]
+	if (space === "srgb-linear") return encode(c)
+	if (space === "display-p3") return encode(mul(XYZ_D65_TO_LINEAR_SRGB, mul(LINEAR_P3_TO_XYZ_D65, [toLinear(c[0]), toLinear(c[1]), toLinear(c[2])])))
+	return null
+}
+
+/** Parses the color forms getComputedStyle returns (rgb/rgba, color(srgb | srgb-linear | display-p3), lab/lch, oklab/oklch) plus hex and `transparent`; other spaces return null. Out-of-gamut values are clamped to sRGB. */
+export function parseColor(input: string): Rgba | null {
+	const s = input.trim().toLowerCase()
+	if (s === "transparent") return TRANSPARENT
+	if (s.startsWith("#")) return parseHex(s)
+	const m = /^(rgba?|color|oklab|oklch|lab|lch)\((.*)\)$/.exec(s)
+	if (!m) return null
+	const [, fn, body = ""] = m
+	const [main = "", alphaPart] = body.split("/")
+	const parts = main.replace(/,/g, " ").split(/\s+/).filter(Boolean)
+	const commaAlpha = fn?.startsWith("rgb") && parts.length === 4 ? parts[3] : undefined
+	const alphaToken = alphaPart?.trim() ?? commaAlpha
+	const a = alphaToken === undefined ? 1 : channel(alphaToken, 1)
+	if (fn === "rgb" || fn === "rgba") return { r: channel(parts[0] ?? "0", 255), g: channel(parts[1] ?? "0", 255), b: channel(parts[2] ?? "0", 255), a }
+	if (fn === "color") {
+		const rgb = predefinedToRgb(parts[0] ?? "", [channel(parts[1] ?? "0", 1), channel(parts[2] ?? "0", 1), channel(parts[3] ?? "0", 1)])
+		return rgb ? { r: rgb[0], g: rgb[1], b: rgb[2], a } : null
+	}
+	if (fn === "lab" || fn === "lch") {
+		const l = channel(parts[0] ?? "0", 100)
+		const [q1, q2] = [Number.parseFloat(parts[1] ?? "0"), Number.parseFloat(parts[2] ?? "0")]
+		const [la, lb] = fn === "lch" ? [q1 * Math.cos((q2 * Math.PI) / 180), q1 * Math.sin((q2 * Math.PI) / 180)] : [q1, q2]
+		const [r, g, b] = labToRgb(l, la, lb)
+		return { r, g, b, a }
+	}
+	const l = channel(parts[0] ?? "0", 1)
+	const [p1, p2] = [Number.parseFloat(parts[1] ?? "0"), Number.parseFloat(parts[2] ?? "0")]
+	const [oa, ob] = fn === "oklch" ? [p1 * Math.cos((p2 * Math.PI) / 180), p1 * Math.sin((p2 * Math.PI) / 180)] : [p1, p2]
+	const [r, g, b] = oklabToRgb(l, oa, ob)
+	return { r, g, b, a }
+}
+
+/** Source-over compositing of `top` onto an opaque `bottom`. */
+export function blend(top: Rgba, bottom: Rgba): Rgba {
+	const a = top.a + bottom.a * (1 - top.a)
+	if (a === 0) return TRANSPARENT
+	const mix = (t: number, b: number): number => (t * top.a + b * bottom.a * (1 - top.a)) / a
+	return { r: mix(top.r, bottom.r), g: mix(top.g, bottom.g), b: mix(top.b, bottom.b), a }
+}
+
+/** WCAG 2.x relative luminance. */
+export function luminance(c: Rgba): number {
+	const lin = (v: number): number => {
+		const s = v / 255
+		return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+	}
+	return 0.2126 * lin(c.r) + 0.7152 * lin(c.g) + 0.0722 * lin(c.b)
+}
+
+/** WCAG 2.x contrast ratio between two opaque colors, 1..21. */
+export function contrastRatio(a: Rgba, b: Rgba): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x)
+	return ((hi ?? 0) + 0.05) / ((lo ?? 0) + 0.05)
+}
+
+export function toHsl(c: Rgba): { readonly h: number; readonly s: number; readonly l: number } {
+	const [r, g, b] = [c.r / 255, c.g / 255, c.b / 255]
+	const max = Math.max(r, g, b)
+	const min = Math.min(r, g, b)
+	const l = (max + min) / 2
+	if (max === min) return { h: 0, s: 0, l }
+	const d = max - min
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+	const h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+	return { h: h * 60, s, l }
+}
+
+/** Every color literal inside a computed value such as `box-shadow` or `background-image`. */
+export function colorsIn(value: string): readonly Rgba[] {
+	const out: Rgba[] = []
+	for (const m of value.matchAll(/(rgba?|color|oklab|oklch|lab|lch)\([^()]*\)|#[0-9a-f]{3,8}\b/gi)) {
+		const c = parseColor(m[0])
+		if (c) out.push(c)
+	}
+	return out
+}

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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;
+	}
+})();`