oh-my-opencode 5.0.0-beta.89 → 5.0.0-beta.90

package/dist/skills/ulw-research/scripts/html-lite.mjs

@@ -0,0 +1,239 @@
+// html-lite.mjs - a dependency-free HTML tokenizer for report checks.
+//
+// Single forward scan with indexOf (no whole-document regex, no backtracking). Produces a
+// LiteNode tree: { tag, attrs, children, parent, line, text, raw }. Text nodes carry
+// tag "#text"; <style>/<script>/<svg> keep their inner source in `raw` and have no parsed
+// children. The "#document" root also carries `ids` (id -> occurrence count) so
+// selectorPath can tell whether an id is unique. Plain Node ESM, no dependencies.
+
+import { decodeEntities } from "./entities.mjs"
+
+export { decodeEntities }
+
+const VOID_TAGS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"])
+const RAW_TAGS = new Set(["style", "script", "svg"])
+const HEADINGS = ["h1", "h2", "h3", "h4", "h5", "h6"]
+const P_CLOSERS = new Set([
+	"address", "article", "blockquote", "details", "div", "dl", "fieldset", "figcaption", "figure", "footer",
+	"form", "header", "hr", "main", "menu", "nav", "ol", "p", "pre", "section", "table", "ul", ...HEADINGS,
+])
+const P_SCOPE = new Set(["td", "th", "caption", "button", "body", "html"])
+const LI_SCOPE = new Set(["ul", "ol", "menu", "body", "html"])
+const PROSE_SKIP = new Set(["code", "pre", "kbd", "samp", "script", "style", "svg"])
+const SAFE_ID = /^[A-Za-z_][\w-]*$/
+
+export const PROSE_TAGS = new Set(["p", "li", ...HEADINGS, "td", "th", "figcaption", "blockquote", "dd", "dt"])
+const PROSE_BREAKS = new Set([...P_CLOSERS, ...PROSE_TAGS, "br", "tr"])
+
+function makeNode(tag, attrs, parent, line) {
+	return { tag, attrs, children: [], parent, line, text: "", raw: null }
+}
+
+function lineStarts(source) {
+	const starts = [0]
+	for (let at = source.indexOf("\n"); at !== -1; at = source.indexOf("\n", at + 1)) starts.push(at + 1)
+	return starts
+}
+
+function lineAt(starts, offset) {
+	let lo = 0
+	let hi = starts.length - 1
+	while (lo < hi) {
+		const mid = (lo + hi + 1) >> 1
+		if (starts[mid] <= offset) lo = mid
+		else hi = mid - 1
+	}
+	return lo + 1
+}
+
+const isSpace = (ch) => ch === " " || ch === "\n" || ch === "\t" || ch === "\r" || ch === "\f"
+const isLetter = (ch) => (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z")
+
+function skipSpaces(source, at) {
+	while (at < source.length && isSpace(source[at])) at++
+	return at
+}
+
+/** Read `<name attrs...>` starting just after `<`. */
+function readTag(source, start) {
+	const end = source.length
+	let at = start
+	while (at < end && !isSpace(source[at]) && source[at] !== ">" && source[at] !== "/") at++
+	const name = source.slice(start, at).toLowerCase()
+	const attrs = {}
+	let selfClosing = false
+	while (at < end) {
+		const ch = source[at]
+		if (isSpace(ch)) { at++; continue }
+		if (ch === ">") return { name, attrs, end: at + 1, selfClosing }
+		selfClosing = ch === "/" && source[at + 1] === ">"
+		if (ch === "/") { at++; continue }
+		let stop = at + 1
+		while (stop < end && !isSpace(source[stop]) && source[stop] !== "/" && source[stop] !== ">" && source[stop] !== "=") stop++
+		const key = source.slice(at, stop).toLowerCase()
+		at = skipSpaces(source, stop)
+		let value = ""
+		if (source[at] === "=") {
+			at = skipSpaces(source, at + 1)
+			const quote = source[at]
+			if (quote === '"' || quote === "'") {
+				const close = source.indexOf(quote, at + 1)
+				const valueEnd = close === -1 ? end : close
+				value = source.slice(at + 1, valueEnd)
+				at = valueEnd + 1
+			} else {
+				let valueEnd = at
+				while (valueEnd < end && !isSpace(source[valueEnd]) && source[valueEnd] !== ">") valueEnd++
+				value = source.slice(at, valueEnd)
+				at = valueEnd
+			}
+		}
+		if (key !== "__proto__" && !Object.hasOwn(attrs, key)) attrs[key] = decodeEntities(value)
+	}
+	return { name, attrs, end, selfClosing }
+}
+
+function tagNameAt(source, at, tag) {
+	if (source.slice(at, at + tag.length).toLowerCase() !== tag) return false
+	const next = source[at + tag.length] ?? ">"
+	return isSpace(next) || next === ">" || next === "/"
+}
+
+/** Find the close of a raw element; nested <svg> is depth-counted. Returns [innerEnd, resumeAt]. */
+function findRawClose(source, from, tag) {
+	let depth = 0
+	for (let lt = source.indexOf("<", from); lt !== -1; lt = source.indexOf("<", lt + 1)) {
+		if (source[lt + 1] === "/" && tagNameAt(source, lt + 2, tag)) {
+			if (depth === 0) {
+				const gt = source.indexOf(">", lt)
+				return [lt, gt === -1 ? source.length : gt + 1]
+			}
+			depth--
+		} else if (tag === "svg" && tagNameAt(source, lt + 1, tag)) {
+			depth++
+		}
+	}
+	return [source.length, source.length]
+}
+
+/** Parse an HTML string into a LiteNode tree rooted at "#document"; never throws on malformed input. */
+export function parseHtml(source) {
+	const src = String(source)
+	const starts = lineStarts(src)
+	const root = makeNode("#document", {}, null, 1)
+	root.ids = new Map()
+	const stack = [root]
+	let sawBody = false
+	let textStart = 0
+	let at = 0
+	const top = () => stack[stack.length - 1]
+	const flushText = (to) => {
+		if (to > textStart) {
+			const node = makeNode("#text", {}, top(), lineAt(starts, textStart))
+			node.text = decodeEntities(src.slice(textStart, to))
+			top().children.push(node)
+		}
+	}
+	const closeWithin = (tag, scope) => {
+		for (let k = stack.length - 1; k > 0; k--) {
+			if (stack[k].tag === tag) { stack.length = k; return }
+			if (scope.has(stack[k].tag)) return
+		}
+	}
+	while (at < src.length) {
+		const lt = src.indexOf("<", at)
+		if (lt === -1) break
+		const next = src[lt + 1] ?? ""
+		if (src.startsWith("<!--", lt)) {
+			flushText(lt)
+			const close = src.indexOf("-->", lt + 4)
+			at = textStart = close === -1 ? src.length : close + 3
+		} else if (next === "!" || next === "?") {
+			flushText(lt)
+			const close = src.indexOf(">", lt)
+			at = textStart = close === -1 ? src.length : close + 1
+		} else if (next === "/" && isLetter(src[lt + 2] ?? "")) {
+			flushText(lt)
+			const tag = readTag(src, lt + 2)
+			if (tag.name !== "body" && tag.name !== "html") {
+				for (let k = stack.length - 1; k > 0; k--) {
+					if (stack[k].tag === tag.name) { stack.length = k; break }
+				}
+			}
+			at = textStart = tag.end
+		} else if (isLetter(next)) {
+			flushText(lt)
+			const tag = readTag(src, lt + 1)
+			at = textStart = tag.end
+			if ((tag.name === "html" || tag.name === "body" || tag.name === "head") && stack.some((n) => n.tag === tag.name)) continue
+			if (P_CLOSERS.has(tag.name)) closeWithin("p", P_SCOPE)
+			if (tag.name === "li") closeWithin("li", LI_SCOPE)
+			const node = makeNode(tag.name, tag.attrs, top(), lineAt(starts, lt))
+			top().children.push(node)
+			if (tag.name === "body") sawBody = true
+			if (tag.attrs.id) root.ids.set(tag.attrs.id, (root.ids.get(tag.attrs.id) ?? 0) + 1)
+			if (RAW_TAGS.has(tag.name)) {
+				node.raw = ""
+				if (!tag.selfClosing) {
+					const [innerEnd, resume] = findRawClose(src, tag.end, tag.name)
+					node.raw = src.slice(tag.end, innerEnd)
+					at = textStart = resume
+				}
+			} else if (!VOID_TAGS.has(tag.name)) {
+				stack.push(node)
+			}
+		} else {
+			at = lt + 1
+		}
+	}
+	flushText(src.length)
+	if (!sawBody) wrapInBody(root)
+	return root
+}
+
+/** Fragments without <body>: move everything except <head> under a synthesized body. */
+function wrapInBody(root) {
+	const host = root.children.find((child) => child.tag === "html") ?? root
+	const kept = host.children.filter((child) => child.tag === "head")
+	const moved = host.children.filter((child) => child.tag !== "head")
+	const body = makeNode("body", {}, host, moved[0]?.line ?? 1)
+	for (const child of moved) child.parent = body
+	body.children = moved
+	host.children = [...kept, body]
+}
+
+function segment(node) {
+	const same = node.parent.children.filter((child) => child.tag === node.tag)
+	return same.length > 1 ? `${node.tag}:nth-of-type(${same.indexOf(node) + 1})` : node.tag
+}
+
+/** CSS selector for a node: nearest unique-id anchor, else `body > tag:nth-of-type(k) > ...`. */
+export function selectorPath(node) {
+	let root = node
+	while (root.parent) root = root.parent
+	const ids = root.ids ?? new Map()
+	const segments = []
+	for (let cur = node.tag === "#text" ? node.parent : node; cur?.parent; cur = cur.parent) {
+		const id = cur.attrs.id
+		if (id && SAFE_ID.test(id) && ids.get(id) === 1) return [`#${id}`, ...segments].join(" > ")
+		if (cur.tag === "body") return ["body", ...segments].join(" > ")
+		if (cur.tag === "html") break
+		segments.unshift(segment(cur))
+	}
+	return segments.join(" > ")
+}
+
+/** Descendant text minus code/pre/kbd/samp/script/style/svg, whitespace collapsed. */
+export function proseText(node) {
+	const parts = []
+	const walk = (cur) => {
+		if (cur.tag === "#text") { parts.push(cur.text); return }
+		if (PROSE_SKIP.has(cur.tag)) return
+		const breaks = PROSE_BREAKS.has(cur.tag)
+		if (breaks) parts.push(" ")
+		for (const child of cur.children) walk(child)
+		if (breaks) parts.push(" ")
+	}
+	for (const child of node.children) walk(child)
+	return parts.join("").replace(/\s+/g, " ").trim()
+}

package/dist/skills/ulw-research/scripts/html-lite.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test"
+
+import { decodeEntities, parseHtml, proseText, PROSE_TAGS, selectorPath } from "./html-lite.mjs"
+
+type LiteNode = {
+	tag: string
+	attrs: Record<string, string>
+	children: LiteNode[]
+	parent: LiteNode | null
+	line: number
+	text: string
+	raw: string | null
+}
+
+function elements(root: LiteNode): LiteNode[] {
+	const out: LiteNode[] = []
+	const stack = [...root.children].reverse()
+	while (stack.length > 0) {
+		const node = stack.pop() as LiteNode
+		if (node.tag === "#text") continue
+		out.push(node)
+		for (let i = node.children.length - 1; i >= 0; i--) stack.push(node.children[i] as LiteNode)
+	}
+	return out
+}
+
+function byTag(root: LiteNode, tag: string): LiteNode[] {
+	return elements(root).filter((node) => node.tag === tag)
+}
+
+function childTags(node: LiteNode): string[] {
+	return node.children.filter((child) => child.tag !== "#text").map((child) => child.tag)
+}
+
+describe("selectorPath", () => {
+	test("#given the 3rd p in the 2nd section under main #when a path is built #then it uses nth-of-type segments under body", () => {
+		// given
+		const doc = parseHtml(
+			"<html><body><main><section><p>x</p></section><section><p>1</p><p>2</p><p>3</p></section></main></body></html>",
+		)
+		const third = byTag(doc, "p")[3] as LiteNode
+		// when
+		const path = selectorPath(third)
+		// then
+		expect(path).toBe("body > main > section:nth-of-type(2) > p:nth-of-type(3)")
+	})
+
+	test("#given an ancestor with a unique id #when a path is built #then it anchors at that id", () => {
+		// given
+		const doc = parseHtml(
+			'<body><main><section id="results"><p>1</p><p>2</p><p>3</p></section></main></body>',
+		)
+		const third = byTag(doc, "p")[2] as LiteNode
+		// when
+		const path = selectorPath(third)
+		// then
+		expect(path).toBe("#results > p:nth-of-type(3)")
+	})
+
+	test("#given a duplicated id #when a path is built #then the id is not used as an anchor", () => {
+		// given
+		const doc = parseHtml('<body><div id="dup"><p>a</p></div><div id="dup"><p>b</p></div></body>')
+		const second = byTag(doc, "p")[1] as LiteNode
+		// when
+		const path = selectorPath(second)
+		// then
+		expect(path).toBe("body > div:nth-of-type(2) > p")
+	})
+})
+
+describe("parseHtml", () => {
+	test("#given a p followed by an h2 #when parsed #then the p auto-closes and h2 is its sibling", () => {
+		// given
+		const source = "<body><p>a<h2>b</h2></body>"
+		// when
+		const doc = parseHtml(source)
+		// then
+		const body = byTag(doc, "body")[0] as LiteNode
+		expect(childTags(body)).toEqual(["p", "h2"])
+		expect((byTag(doc, "h2")[0] as LiteNode).parent).toBe(body)
+	})
+
+	test("#given consecutive li without close tags #when parsed #then each li is a sibling", () => {
+		// given
+		const source = "<body><ul><li>one<li>two<li>three</ul></body>"
+		// when
+		const doc = parseHtml(source)
+		// then
+		const list = byTag(doc, "ul")[0] as LiteNode
+		expect(childTags(list)).toEqual(["li", "li", "li"])
+	})
+
+	test("#given an element on source line 7 #when parsed #then its line is 7", () => {
+		// given
+		const source = ["<html>", "<body>", "<main>", "<section>", "<p>one</p>", "<p>two</p>", '<p id="seven">x</p>', "</section>"].join("\n")
+		// when
+		const doc = parseHtml(source)
+		// then
+		const seven = byTag(doc, "p").find((node) => node.attrs.id === "seven") as LiteNode
+		expect(seven.line).toBe(7)
+	})
+
+	test("#given comments, void tags and an unmatched close tag #when parsed #then comments vanish, voids stay leaves, the stray close is ignored", () => {
+		// given
+		const source = "<body><!-- <p>hidden</p> --><div>a<br>b<img src=x.png></span> c</div></body>"
+		// when
+		const doc = parseHtml(source)
+		// then
+		expect(byTag(doc, "p")).toHaveLength(0)
+		const div = byTag(doc, "div")[0] as LiteNode
+		expect(childTags(div)).toEqual(["br", "img"])
+		expect((byTag(doc, "br")[0] as LiteNode).children).toHaveLength(0)
+		expect((byTag(doc, "img")[0] as LiteNode).attrs.src).toBe("x.png")
+		expect(proseText(div)).toBe("a b c")
+	})
+
+	test("#given style, script and svg elements #when parsed #then their inner source is captured raw", () => {
+		// given
+		const source =
+			'<head><style>p > a { color: red }</style></head><body><script>if (a < b) {}</script><svg viewBox="0 0 1 1"><svg><text>t</text></svg></svg><p>after</p></body>'
+		// when
+		const doc = parseHtml(source)
+		// then
+		expect((byTag(doc, "style")[0] as LiteNode).raw).toBe("p > a { color: red }")
+		expect((byTag(doc, "script")[0] as LiteNode).raw).toBe("if (a < b) {}")
+		const svg = byTag(doc, "svg")[0] as LiteNode
+		expect(svg.raw).toBe("<svg><text>t</text></svg>")
+		expect(svg.attrs.viewbox).toBe("0 0 1 1")
+		expect(childTags(svg.parent as LiteNode)).toEqual(["script", "svg", "p"])
+	})
+
+	test("#given an unclosed fragment without body #when parsed #then the tree still has body > div > p", () => {
+		// given
+		const source = "<div><p>unclosed"
+		// when
+		const doc = parseHtml(source)
+		// then
+		const p = byTag(doc, "p")[0] as LiteNode
+		expect(p.parent?.tag).toBe("div")
+		expect(p.parent?.parent?.tag).toBe("body")
+		expect(selectorPath(p)).toBe("body > div > p")
+		expect(proseText(p)).toBe("unclosed")
+	})
+
+	test("#given attributes in every quoting style #when parsed #then values are decoded", () => {
+		// given
+		const source = `<body><a href="#s1" data-x='y &amp; z' hidden title=bare>k</a></body>`
+		// when
+		const doc = parseHtml(source)
+		// then
+		const anchor = byTag(doc, "a")[0] as LiteNode
+		expect(anchor.attrs).toEqual({ href: "#s1", "data-x": "y & z", hidden: "", title: "bare" })
+	})
+})
+
+describe("decodeEntities", () => {
+	test("#given &mdash; #when decoded #then it is U+2014", () => {
+		expect(decodeEntities("a&mdash;b")).toBe("a\u2014b")
+	})
+
+	test("#given named, decimal and hex entities #when decoded #then each maps to its code point", () => {
+		// given
+		const source = "&amp;&lt;&gt;&quot;&apos;&nbsp;&ndash;&hellip;&copy;&reg;&times;&middot;&#44;&#x1F600;"
+		// when
+		const decoded = decodeEntities(source)
+		// then
+		expect(decoded).toBe("&<>\"'\u00a0\u2013\u2026\u00a9\u00ae\u00d7\u00b7,\u{1F600}")
+	})
+
+	test("#given unknown or malformed entities #when decoded #then they are left verbatim", () => {
+		expect(decodeEntities("&bogus; & &#xZZ; AT&T")).toBe("&bogus; & &#xZZ; AT&T")
+	})
+})
+
+describe("proseText", () => {
+	test("#given a paragraph with inline code #when prose is extracted #then code is skipped and whitespace collapsed", () => {
+		// given
+		const doc = parseHtml("<body><p>Run   <code>npm i</code>\n then <kbd>Enter</kbd> now</p></body>")
+		const p = byTag(doc, "p")[0] as LiteNode
+		// when
+		const prose = proseText(p)
+		// then
+		expect(prose).toBe("Run then now")
+	})
+
+	test("#given PROSE_TAGS #when read #then it holds the prose-bearing tags", () => {
+		expect([...PROSE_TAGS].sort()).toEqual(
+			["blockquote", "dd", "dt", "figcaption", "h1", "h2", "h3", "h4", "h5", "h6", "li", "p", "td", "th"].sort(),
+		)
+	})
+})

package/dist/skills/ulw-research/scripts/layout-probe.mjs

@@ -0,0 +1,83 @@
+// layout-probe.mjs - the in-page probe the layout gates consume.
+//
+// buildProbeSource() returns ONE async IIFE expression (the engine's evaluate awaits it): it first
+// forces lazy images to load eagerly and awaits their decode (bounded), so natural sizes are real. The orchestrator evaluates it in the rendered
+// report through the browser skill's owned headless engine and writes the result to boxes.json;
+// gates-layout.mjs reads that file. This module never launches a browser.
+//
+// Selector paths use the SAME rule as html-lite.selectorPath (a unique safe #id anchors the path,
+// otherwise tag segments with :nth-of-type(k) only when the parent has more than one child of that
+// tag, prefixed "body"), so a layout defect can be mapped back to the static tree. The rule lives in
+// PATH_FUNCTION_SOURCE, embedded verbatim in the probe and exercised by the parity test.
+
+export const PROBE_VERSION = 1
+export const SAMPLED_SELECTOR = "figure, .fig, img, svg, table, h1, h2, h3, p, pre"
+export const EXCLUDED_ANCESTORS = Object.freeze(["svg", "nav", "header", "footer"])
+
+/** In-page path rule. idCount(id) returns how many elements carry that id. */
+export const PATH_FUNCTION_SOURCE = `function ulwSelectorPath(el, idCount) {
+	const SAFE_ID = /^[A-Za-z_][\\w-]*$/;
+	const segments = [];
+	for (let cur = el; cur && cur.parentElement; cur = cur.parentElement) {
+		const tag = cur.tagName.toLowerCase();
+		const id = cur.id;
+		if (id && SAFE_ID.test(id) && idCount(id) === 1) return ["#" + id].concat(segments).join(" > ");
+		if (tag === "body") return ["body"].concat(segments).join(" > ");
+		if (tag === "html") break;
+		const same = Array.from(cur.parentElement.children).filter((c) => c.tagName === cur.tagName);
+		segments.unshift(same.length > 1 ? tag + ":nth-of-type(" + (same.indexOf(cur) + 1) + ")" : tag);
+	}
+	return segments.join(" > ");
+}`
+
+export class ProbeError extends Error {
+	constructor(code, message) {
+		super(message)
+		this.name = "ProbeError"
+		this.code = code
+	}
+}
+
+/** @param {{ cap?: number, root?: string }} [options] */
+export function buildProbeSource({ cap = 400, root = "main, article" } = {}) {
+	if (!Number.isInteger(cap) || cap <= 0) throw new ProbeError("invalid_cap", `--cap requires a positive integer, got ${cap}`)
+	if (typeof root !== "string" || root.trim().length === 0) throw new ProbeError("invalid_root", "--root requires a non-empty CSS selector")
+	return `(async () => {
+	const CAP = ${cap};
+	const IMAGE_WAIT_MS = 5000;
+	const ROOT = document.querySelector(${JSON.stringify(root)}) || document.body;
+	const EXCLUDED = ${JSON.stringify(EXCLUDED_ANCESTORS)};
+	const images = Array.from(document.images);
+	for (const img of images) if (img.loading === "lazy") img.loading = "eager";
+	const settle = Promise.all(images.map((img) => (img.complete && img.naturalWidth > 0 ? null : img.decode().catch(() => null))));
+	await Promise.race([settle, new Promise((resolve) => setTimeout(resolve, IMAGE_WAIT_MS))]);
+	${PATH_FUNCTION_SOURCE}
+	const idCount = (id) => document.querySelectorAll("#" + CSS.escape(id)).length;
+	const path = (el) => ulwSelectorPath(el, idCount);
+	const r1 = (n) => Math.round(n * 10) / 10;
+	const rect = (el) => { const b = el.getBoundingClientRect(); return { x: r1(b.left + scrollX), y: r1(b.top + scrollY), w: r1(b.width), h: r1(b.height) }; };
+	const excluded = (el) => { for (let p = el.parentElement; p; p = p.parentElement) if (EXCLUDED.includes(p.tagName.toLowerCase())) return true; return false; };
+	const all = Array.from(ROOT.querySelectorAll(${JSON.stringify(SAMPLED_SELECTOR)})).filter((el) => {
+		if (excluded(el)) return false;
+		const b = el.getBoundingClientRect();
+		return b.width > 0 || b.height > 0;
+	});
+	const boxes = all.slice(0, CAP).map((el) => {
+		const cs = getComputedStyle(el);
+		const parent = el.parentElement;
+		const box = {
+			selector: path(el), tag: el.tagName.toLowerCase(), rect: rect(el),
+			parentSelector: parent ? path(parent) : null, parentRect: parent ? rect(parent) : null,
+			parentOverflow: parent ? { x: getComputedStyle(parent).overflowX, y: getComputedStyle(parent).overflowY } : null,
+			scroll: { sw: el.scrollWidth, cw: el.clientWidth, sh: el.scrollHeight, ch: el.clientHeight },
+			overflow: { x: cs.overflowX, y: cs.overflowY }, position: cs.position,
+			textLen: (el.textContent || "").trim().length,
+		};
+		if (el.tagName === "IMG") { box.objectFit = cs.objectFit; box.natural = { w: el.naturalWidth, h: el.naturalHeight }; }
+		return box;
+	});
+	return { probe_version: ${PROBE_VERSION}, viewport: { w: innerWidth, h: innerHeight },
+		document: { w: document.documentElement.scrollWidth, h: document.documentElement.scrollHeight },
+		count: all.length, truncated: all.length > CAP, boxes };
+})()`
+}

package/dist/skills/ulw-research/scripts/layout-probe.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test"
+
+import { parseHtml, selectorPath } from "./html-lite.mjs"
+import { buildProbeSource, PATH_FUNCTION_SOURCE, PROBE_VERSION, ProbeError } from "./layout-probe.mjs"
+
+// A minimal element adapter over the html-lite tree: exactly the DOM surface the path rule reads.
+function adapt(node, parentAdapter, cache) {
+	if (cache.has(node)) return cache.get(node)
+	const el = { tagName: node.tag.toUpperCase(), id: node.attrs.id ?? "", parentElement: parentAdapter, children: [] }
+	cache.set(node, el)
+	el.children = node.children.filter((c) => c.tag !== "#text").map((c) => adapt(c, el, cache))
+	return el
+}
+
+function pathRule() {
+	return new Function(`${PATH_FUNCTION_SOURCE}; return ulwSelectorPath;`)()
+}
+
+const FIXTURE = `<!doctype html><html><head><style>p{}</style></head><body>
+<main id="top"><section><h2>A</h2><p>one</p><p>two</p><figure class="fig"><img src="a.png"><figcaption>c</figcaption></figure></section>
+<section id="results"><h2>B</h2><p>x</p><figure><svg width="300"><text>t</text></svg></figure><figure><img src="b.png"></figure></section>
+<section><div id="dup"></div><div id="dup"><p>y</p></div></section></main></body></html>`
+
+describe("PATH_FUNCTION_SOURCE", () => {
+	test("#given the html-lite tree of a fixture #when the in-page path rule runs on an adapter of every element #then it equals html-lite selectorPath", () => {
+		// given
+		const doc = parseHtml(FIXTURE)
+		const ids = new Map()
+		const cache = new Map()
+		const elements = []
+		const walk = (node, parentAdapter) => {
+			if (node.tag === "#text") return
+			const el = adapt(node, parentAdapter, cache)
+			if (node.tag !== "#root" && node.parent) elements.push([node, el])
+			if (el.id) ids.set(el.id, (ids.get(el.id) ?? 0) + 1)
+			for (const child of node.children) walk(child, el)
+		}
+		walk(doc, null)
+		const rule = pathRule()
+		// when
+		const mismatches = elements
+			.filter(([node]) => node.tag !== "html" && node.tag !== "head" && node.tag !== "#root")
+			.map(([node, el]) => [selectorPath(node), rule(el, (id) => ids.get(id) ?? 0)])
+			.filter(([expected, actual]) => expected !== actual)
+		// then
+		expect(elements.length).toBeGreaterThan(10)
+		expect(mismatches).toEqual([])
+	})
+
+	test("#given a duplicated id #when a descendant path is built #then the duplicate is not used as an anchor", () => {
+		const doc = parseHtml(FIXTURE)
+		const p = []
+		const find = (n) => { if (n.tag === "p" && n.parent?.attrs.id === "dup") p.push(n); n.children.forEach(find) }
+		find(doc)
+		expect(selectorPath(p[0])).toBe("#top > section:nth-of-type(3) > div:nth-of-type(2) > p")
+	})
+})
+
+describe("buildProbeSource", () => {
+	test("#given defaults #when built #then it is one async IIFE expression that parses and carries the version, cap, and image wait", () => {
+		const src = buildProbeSource()
+		expect(src).toMatch(/^\(async \(\) => \{[\s\S]*\}\)\(\)\s*$/)
+		expect(src.includes('img.loading = "eager"')).toBe(true)
+		expect(() => new Function(`return ${src}`)).not.toThrow()
+		expect(src.includes("const CAP = 400;")).toBe(true)
+		expect(src.includes(`probe_version: ${PROBE_VERSION}`)).toBe(true)
+	})
+
+	test("#given cap 50 and a custom root #when built #then both are embedded as literals", () => {
+		const src = buildProbeSource({ cap: 50, root: "article.report" })
+		expect(src.includes("const CAP = 50;")).toBe(true)
+		expect(src.includes('document.querySelector("article.report")')).toBe(true)
+	})
+
+	test("#given cap 0 or a fractional cap #when built #then a typed ProbeError is thrown", () => {
+		expect(() => buildProbeSource({ cap: 0 })).toThrow(ProbeError)
+		expect(() => buildProbeSource({ cap: 1.5 })).toThrow(ProbeError)
+	})
+
+	test("#given an empty root #when built #then a typed ProbeError is thrown", () => {
+		expect(() => buildProbeSource({ root: "" })).toThrow(ProbeError)
+		expect(() => buildProbeSource({ root: "   " })).toThrow(ProbeError)
+	})
+
+	test("#given a root containing a double quote #when built #then the source still parses", () => {
+		const src = buildProbeSource({ root: 'main[data-x="1"]' })
+		expect(() => new Function(`return ${src}`)).not.toThrow()
+	})
+})