webview-preview 1.1.1 → 1.2.0

package/src/engines/playwright.mjs

@@ -19,13 +19,15 @@ const loadPlaywright = async () => {
 export const runPlaywright = async ({
 	engine, url, steps, init = [], size, locale,
 	colorScheme, isMotionReduced = false, out, prefix, scale,
-	snapMargin = 8, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, log
+	snapMargin = 8, isHeaded = false, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, log
 }) => {
+	const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Infinity;
 	const playwright = await loadPlaywright();
 	const browserType = engine === "webkit" ? playwright.webkit : playwright.chromium;
-	const browser = await browserType.launch({ channel: CHANNELS[engine], headless: true });
+	const browser = await browserType.launch({ channel: CHANNELS[engine], headless: !isHeaded });
 	const saved = [];
 	const films = [];
+	const annotations = [];
 	let failed = false;
 
 	try {
@@ -70,8 +72,68 @@ export const runPlaywright = async ({
 			films.push({ name: step.value, file: path.join(out, `${prefix}${step.value}.png`), scale: scale ?? 1, viewport: page.viewportSize(), frames });
 		}
 
+		const cutOut = async (rect, file) => {
+			try {
+				await page.screenshot({ path: file, clip: clipRect(rect, snapMargin, page.viewportSize()) });
+				return path.basename(file);
+			} catch {
+				return null;
+			}
+		}
+
+		const annotate = async step => {
+			const base = `${prefix}annotate-${step.value}`;
+			const images = {}
+			let draft = null;
+			await page.evaluate(step.start);
+			for (;;) {
+				if (page.isClosed()) {
+					annotations.push({ name: step.value, status: "cancelled", result: null });
+					return;
+				}
+				if (Date.now() > deadline) {
+					annotations.push({ name: step.value, status: "cancelled", result: null });
+					throw new Error(`timed out after ${timeoutMs} ms`);
+				}
+				const text = await page.evaluate(step.check).catch(() => null);
+				const answer = text && text !== "missing" ? JSON.parse(text) : null;
+				if (text === "missing") {
+					await page.evaluate(`${draft ? `window.${step.restoreKey} = ${JSON.stringify(draft)};` : ""}${step.start}`).catch(() => undefined);
+				} else if (answer?.status === "open") {
+					if (answer.draft) draft = answer.draft;
+					if (answer.captures?.length) {
+						await page.evaluate(step.hide).catch(() => undefined);
+						await page.waitForTimeout(80);
+						for (const capture of answer.captures) {
+							const image = await cutOut(capture.rect, path.join(out, `${base}-${capture.id}.png`));
+							if (image) images[capture.id] = image;
+						}
+						await page.evaluate(step.show).catch(() => undefined);
+					}
+				} else if (answer) {
+					const annotation = { ...answer, name: step.value, scale: scale ?? 1 }
+					if (annotation.status === "done" && annotation.result) {
+						await page.screenshot({ path: path.join(out, `${base}.png`) });
+						annotation.image = `${base}.png`;
+						await page.evaluate(step.cleanup).catch(() => undefined);
+						await page.waitForTimeout(160);
+						for (const [id, element] of Object.entries(annotation.result.elements)) {
+							element.image = element.isLive
+								? await cutOut(element.rect, path.join(out, `${base}-${id}.png`)) ?? images[id] ?? null
+								: images[id] ?? null;
+						}
+						await page.evaluate(step.dispose).catch(() => undefined);
+					}
+					annotations.push(annotation);
+					return;
+				}
+				await new Promise(resolve => setTimeout(resolve, step.pollMs));
+			}
+		}
+
 		const runStep = async step => {
 			const { kind, value } = step;
+			if (kind === "annotate") return annotate(step);
 			if (kind === "snap") {
 				const file = path.join(out, `${prefix}${value}.png`);
 				const clip = step.selector ? clipRect(await elementRect(step), snapMargin, page.viewportSize()) : undefined;
@@ -113,6 +175,11 @@ export const runPlaywright = async ({
 		}
 
 		for (const step of steps) {
+			if (Date.now() > deadline) {
+				failed = true;
+				log.error(`timed out after ${timeoutMs} ms`);
+				break;
+			}
 			try {
 				await runStep(step);
 			} catch (error) {
@@ -127,5 +194,5 @@ export const runPlaywright = async ({
 		await browser.close();
 	}
 
-	return { saved, failed, films }
+	return { saved, failed, films, annotations }
 }

package/src/engines/webkitgtk.mjs

@@ -48,6 +48,7 @@ export const runWebkitGtk = ({
 
 	const saved = [];
 	const films = [];
+	const annotations = [];
 	let buffer = "";
 	child.stdout.setEncoding("utf8");
 	child.stdout.on("data", chunk => {
@@ -61,6 +62,7 @@ export const runWebkitGtk = ({
 			const value = JSON.parse(line.slice(tab + 1));
 			if (kind === "saved") saved.push(value);
 			else if (kind === "film") films.push(value);
+			else if (kind === "annotate") annotations.push(value);
 			else if (kind === "print") log.info(value);
 			else if (kind === "error") log.error(value);
 			else if (kind === "init-errors") reportInitErrors(value, log);
@@ -73,5 +75,5 @@ export const runWebkitGtk = ({
 		}
 	});
 	child.once("error", reject);
-	child.once("exit", code => resolve({ saved, failed: code !== 0, films }));
+	child.once("exit", code => resolve({ saved, failed: code !== 0, films, annotations }));
 });

package/src/engines/webkitgtk.py

@@ -17,6 +17,7 @@ INPUT_SETTLE_MS = 50
 UNSUPPORTED_RESULT = "Unsupported result type"
 KEY_POLL_MS = 20
 KEY_WAIT_MS = 2000
+ANNOTATE_SETTLE_MS = 80
 KEYUPS = "window.__webviewPreviewKeyups || 0"
 KEYUP_COUNTER = "addEventListener('keyup', () => { window.__webviewPreviewKeyups = (window.__webviewPreviewKeyups || 0) + 1 }, true);"
 GDK_KEY_NAMES = {
@@ -149,7 +150,10 @@ def main():
         if found and entries:
             event.key.hardware_keycode = entries[0].keycode
         event.set_device(seat.get_keyboard())
-        deliver(event)
+        if kind == Gdk.EventType.KEY_RELEASE:
+            Gtk.main_do_event(event)
+        else:
+            deliver(event)
 
     def press(keyval, modifiers=()):
         mask = Gdk.ModifierType(0)
@@ -162,22 +166,31 @@ def main():
             key_event(Gdk.EventType.KEY_RELEASE, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
             mask &= ~MODIFIER_MASKS[modifier]
 
-    def press_all(presses):
+    def press_all(label, presses):
         def count(text):
             return int(text) if text and text.isdigit() else 0
 
         def send(text):
-            expected = count(text) + sum(1 + len(modifiers) for _, modifiers in presses)
+            start = count(text)
+            expected = start + sum(1 + len(modifiers) for _, modifiers in presses)
             for keyval, modifiers in presses:
                 press(keyval, modifiers)
-            started = GLib.get_monotonic_time()
+            progress = {"keyups": start, "since": GLib.get_monotonic_time()}
 
             def check():
                 def on_value(text):
-                    if count(text) >= expected or (GLib.get_monotonic_time() - started) / 1000 >= KEY_WAIT_MS:
+                    keyups = count(text)
+                    if keyups >= expected:
                         GLib.timeout_add(INPUT_SETTLE_MS, run_step)
-                    else:
-                        GLib.timeout_add(KEY_POLL_MS, lambda: (check(), False)[1])
+                        return
+                    now = GLib.get_monotonic_time()
+                    if keyups > progress["keyups"]:
+                        progress.update(keyups=keyups, since=now)
+                    elif (now - progress["since"]) / 1000 >= KEY_WAIT_MS:
+                        step_failed(f"{label}: only {keyups - start} of {expected - start} key presses reached the page")
+                        GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+                        return
+                    GLib.timeout_add(KEY_POLL_MS, lambda: (check(), False)[1])
 
                 evaluate(KEYUPS, on_value, lambda _: GLib.timeout_add(INPUT_SETTLE_MS, run_step))
 
@@ -205,10 +218,11 @@ def main():
             )
         return window.get_pixbuf()
 
-    def save(name, pixbuf):
+    def save(name, pixbuf, is_snapshot=True):
         path = os.path.join(args.out, f"{args.prefix}{name}.png")
         pixbuf.savev(path, "png", [], [])
-        emit("saved", path)
+        if is_snapshot:
+            emit("saved", path)
 
     def evaluate(code, on_value, on_error):
         def on_result(webview, result):
@@ -234,7 +248,7 @@ def main():
 
         evaluate(step["rect"], on_value, lambda error: (step_failed(f"{step['kind']}:{step['value']} failed: {error}"), next_step()))
 
-    def snap_element(step, rect):
+    def crop(name, rect, is_snapshot=True):
         pixbuf = full_pixbuf()
         width, height = view.get_allocated_width(), view.get_allocated_height()
         scale = pixbuf.get_width() / width
@@ -244,12 +258,16 @@ def main():
         right = min(width, int(rect["x"] + rect["width"] + margin + 0.999))
         bottom = min(height, int(rect["y"] + rect["height"] + margin + 0.999))
         if right <= left or bottom <= top:
-            step_failed(f"snap:{step['value']} failed: element is outside the window")
-            return next_step()
+            return None
         cropped = pixbuf.new_subpixbuf(
             int(left * scale), int(top * scale), int((right - left) * scale), int((bottom - top) * scale)
         ).copy()
-        save(step["value"], cropped)
+        save(name, cropped, is_snapshot)
+        return os.path.join(args.out, f"{args.prefix}{name}.png")
+
+    def snap_element(step, rect):
+        if not crop(step["value"], rect):
+            step_failed(f"snap:{step['value']} failed: element is outside the window")
         next_step()
 
     def point_at(step, rect):
@@ -313,6 +331,72 @@ def main():
     def next_step():
         GLib.idle_add(run_step)
 
+    def annotate(step):
+        base = f"annotate-{step['value']}"
+        images = {}
+        memory = {"draft": None}
+
+        def later(callback, ms):
+            GLib.timeout_add(ms, lambda: (callback(), False)[1])
+
+        def again():
+            later(poll, step["pollMs"])
+
+        def restart():
+            draft = memory["draft"]
+            code = (f"window.{step['restoreKey']} = {json.dumps(draft)};" if draft else "") + step["start"]
+            evaluate(code, lambda _: again(), lambda _: again())
+
+        def grab(captures):
+            def shoot():
+                for capture in captures:
+                    path = crop(f"{base}-{capture['id']}", capture["rect"], False)
+                    if path:
+                        images[capture["id"]] = os.path.basename(path)
+                evaluate(step["show"], lambda _: again(), lambda _: again())
+
+            evaluate(step["hide"], lambda _: later(shoot, ANNOTATE_SETTLE_MS), lambda _: shoot())
+
+        def finish_annotate(answer):
+            state["annotating"] = None
+            result = answer.get("result")
+            width = view.get_allocated_width()
+            answer.update(name=step["value"], scale=full_pixbuf().get_width() / width if width else 1)
+            if answer.get("status") != "done" or not result:
+                emit("annotate", answer)
+                return next_step()
+            save(base, full_pixbuf(), False)
+            answer["image"] = f"{args.prefix}{base}.png"
+
+            def crops():
+                for element_id, element in result["elements"].items():
+                    path = crop(f"{base}-{element_id}", element["rect"], False) if element.get("isLive") else None
+                    element["image"] = os.path.basename(path) if path else images.get(element_id)
+                emit("annotate", answer)
+                evaluate(step["dispose"], lambda _: next_step(), lambda _: next_step())
+
+            evaluate(step["cleanup"], lambda _: later(crops, ANNOTATE_SETTLE_MS * 2), lambda _: crops())
+
+        def poll():
+            def on_value(text):
+                if text == "missing":
+                    return restart()
+                if not text or text == "null":
+                    return again()
+                answer = json.loads(text)
+                if answer.get("status") != "open":
+                    return finish_annotate(answer)
+                if answer.get("draft"):
+                    memory["draft"] = answer["draft"]
+                if answer.get("captures"):
+                    return grab(answer["captures"])
+                again()
+
+            evaluate(step["check"], on_value, lambda _: again())
+
+        state["annotating"] = step["value"]
+        evaluate(step["start"], lambda _: poll(), lambda error: (step_failed(f"annotate failed: {error}"), next_step()))
+
     def run_step():
         if state["index"] >= len(steps):
             return finish()
@@ -328,6 +412,8 @@ def main():
                 next_step()
         elif kind == "film":
             film(step)
+        elif kind == "annotate":
+            annotate(step)
         elif kind in ("js", "jsnow"):
             evaluate(value, lambda _: None, lambda error: None if UNSUPPORTED_RESULT in error else emit("error", f"js failed: {error}"))
             if kind == "js":
@@ -364,9 +450,9 @@ def main():
         elif kind in ("hover", "click"):
             with_rect(step, lambda rect: point_at(step, rect))
         elif kind == "key":
-            press_all([(keyval_for(step["key"]), step["modifiers"])])
+            press_all(f"key:{value}", [(keyval_for(step["key"]), step["modifiers"])])
         elif kind == "type":
-            press_all([(Gdk.unicode_to_keyval(ord(character)), ()) for character in value])
+            press_all("type", [(Gdk.unicode_to_keyval(ord(character)), ()) for character in value])
         return False
 
     def start_steps():
@@ -386,6 +472,8 @@ def main():
             GLib.timeout_add(args.load_settle_ms, start_steps)
 
     def on_load_failed(_view, _event, uri, error):
+        if error.matches(WebKit2.NetworkError.quark(), WebKit2.NetworkError.CANCELLED):
+            return False
         emit("error", f"failed to load {uri}: {error.message}")
         return finish(failed=True)
 
@@ -393,10 +481,21 @@ def main():
         emit("error", f"timed out after {args.timeout_ms} ms")
         return finish(failed=True)
 
+    def on_close(*_):
+        if state.get("annotating"):
+            emit("annotate", {"name": state["annotating"], "status": "cancelled", "result": None})
+        skipped = [step for step in steps[state["index"]:] if not step.get("isInternal")]
+        if skipped:
+            emit("error", f"window closed — {len(skipped)} step(s) not run")
+        finish(failed=bool(skipped))
+        return True
+
+    window.connect("delete-event", on_close)
     view.connect("load-changed", on_load_changed)
     view.connect("load-failed", on_load_failed)
     view.load_uri(args.url)
-    GLib.timeout_add(args.timeout_ms, on_timeout)
+    if args.timeout_ms > 0:
+        GLib.timeout_add(args.timeout_ms, on_timeout)
     Gtk.main()
 
     sys.stdout.flush()

package/src/index.d.ts

@@ -13,6 +13,8 @@ export type Step =
 	| `film:${string}:${number}/${number}`
 	| `film:${string}:${number}@${string}`
 	| `film:${string}:${number}/${number}@${string}`
+	| "annotate"
+	| `annotate:${string}`
 	| "offline"
 	| "online"
 	| `latency:${number}`
@@ -53,6 +55,7 @@ export interface PreviewConfig {
 	headed?: boolean;
 	keepStorage?: boolean;
 	waitTimeout?: number;
+	timeout?: number;
 	snapMargin?: number;
 	compare?: boolean;
 	updateBaseline?: boolean;
@@ -63,6 +66,7 @@ export interface PreviewConfig {
 	globals?: Record<string, unknown>;
 	locale?: string;
 	macros?: Record<string, Step[] | string[]>;
+	annotate?: { private?: string[] }
 	failOnError?: boolean;
 }
 
@@ -88,6 +92,7 @@ export interface MockResponse {
 export type InitEntry = string | { file: string }
 
 export interface PreviewOptions extends PreviewConfig {
+	private?: string | string[];
 	target?: string;
 	steps?: Step[] | string[];
 	initFile?: string | string[];
@@ -96,11 +101,56 @@ export interface PreviewOptions extends PreviewConfig {
 	log?: { info: (message: string) => void; error: (message: string) => void }
 }
 
+export interface AnnotationSource {
+	file: string;
+	line: number | null;
+	column: number | null;
+	how: "debug-source" | "debug-stack" | "vue-file";
+	confidence?: "exact" | "nearest" | "file";
+	isMapped?: false;
+}
+
+export interface AnnotationElement {
+	selector: string;
+	selectorQuality: "stable" | "positional";
+	tag: string;
+	role: string | null;
+	name: string | null;
+	text: string | null;
+	label: string;
+	component: {
+		name: string | null;
+		framework: "react" | "vue";
+		chain: { name: string; usedAt: AnnotationSource | null }[];
+		source: AnnotationSource | null;
+	} | null;
+	box: { margin: string; padding: string; border: string; borderRadius: string }
+	style: { display: string; font: string; color: string; background: string; opacity: string; gap: string }
+	rect: { x: number; y: number; width: number; height: number }
+	url: string;
+	isLive: boolean;
+	isPrivate: boolean;
+	image: string | null;
+}
+
+export interface Annotation {
+	version: 1;
+	name: string;
+	status: "done" | "cancelled";
+	page: { url: string; route: string; engine: Exclude<Engine, "auto">; size: { width: number; height: number }; scale: number; takenAt: string }
+	image: string | null;
+	notes: { id: number; text: string; elements: string[]; url: string; isFrozen: boolean }[];
+	maskedCount: number;
+	generalNote: string | null;
+	elements: Record<string, AnnotationElement>;
+}
+
 export interface PreviewResult {
 	engine: Exclude<Engine, "auto">;
 	url: string;
 	sizes: string[];
 	saved: string[];
+	annotations: (Annotation | { name: string; status: "cancelled"; result: null })[];
 	consoleErrors: number;
 	failedAsserts: number;
 	report?: string;

package/src/index.mjs

@@ -11,7 +11,11 @@ import { resolveInit, wrapInit } from "#src/page/init.mjs";
 import { compileMock, mockScript, resolveMockFiles } from "#src/page/mock.mjs";
 import { startServer } from "#src/core/server.mjs";
 import { watchFiles } from "#src/core/watch.mjs";
-import { expandMacros, parseSize, parseSteps } from "#src/core/steps.mjs";
+import { expandMacros, parseSize, parseSteps, runTimeoutMs } from "#src/core/steps.mjs";
+import { loadAnnotateKeys, saveAnnotateKeys } from "#src/core/annotate-settings.mjs";
+import { writeAnnotationReport } from "#src/core/annotate-report.mjs";
+import { createSourceResolver } from "#src/core/source-map.mjs";
+import { annotateStep, formatAnnotation } from "#src/page/annotate/index.mjs";
 import { checkLatency, networkScript } from "#src/page/network.mjs";
 import { resolveTauri, tauriScript } from "#src/page/tauri.mjs";
 
@@ -50,13 +54,27 @@ const checkColorScheme = value => {
 	return value;
 }
 
+const resolveSources = async (annotation, baseDir) => {
+	const resolve = createSourceResolver(baseDir);
+	for (const element of Object.values(annotation.result?.elements ?? {})) {
+		const { component } = element;
+		if (!component) continue;
+		const confidence = component.source?.confidence;
+		component.source = component.source && { ...await resolve(component.source), confidence }
+		component.chain = await Promise.all(component.chain.map(async item => ({ name: item.name, usedAt: await resolve(item.usedAt) })));
+	}
+}
+
 export const preview = async (options = {}) => {
 	const config = options.config === false ? {} : await loadConfig(options.config);
 	const merged = { ...DEFAULTS, ...config, ...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)) }
 	const baseDir = config.configDir ?? process.cwd();
 	const engine = resolveEngine(merged.engine);
 	const macros = { ...config.macros, ...options.macros }
-	const steps = parseSteps(expandMacros(merged.steps.length ? merged.steps : DEFAULTS.steps, macros));
+	const parsedSteps = parseSteps(expandMacros(merged.steps.length ? merged.steps : DEFAULTS.steps, macros));
+	const savedKeys = parsedSteps.some(step => step.kind === "annotate") ? loadAnnotateKeys() : null;
+	const privateSelectors = [...(config.annotate?.private ?? []), ...[].concat(options.private ?? [])].map(String);
+	const steps = parsedSteps.map(step => step.kind === "annotate" ? annotateStep(step.value, savedKeys, privateSelectors) : step);
 	const out = path.resolve(baseDir, merged.out);
 	const url = resolveUrl(merged.target ?? merged.url ?? "/", merged.baseUrl);
 	const sizes = parseSizes(merged.size);
@@ -112,7 +130,8 @@ export const preview = async (options = {}) => {
 	const stopServer = await startServer(server);
 	try {
 		const prefix = merged.prefix ?? `${engine}-`;
-		const result = { saved: [], failed: false }
+		const result = { saved: [], failed: false, annotations: [] }
+		const hasAnnotate = steps.some(step => step.kind === "annotate");
 		for (const size of sizes) {
 			if (sizes.length > 1) output.log.info(`size ${size}`);
 			const run = await runEngine(engine, {
@@ -127,12 +146,37 @@ export const preview = async (options = {}) => {
 				prefix: sizes.length > 1 ? `${prefix}${size}-` : prefix,
 				scale: merged.scale === undefined ? undefined : Number(merged.scale),
 				snapMargin,
-				isHeaded: !!merged.headed,
+				isHeaded: merged.headed === undefined ? hasAnnotate : !!merged.headed,
 				isStorageKept: !!merged.keepStorage,
 				waitForTimeoutMs: Number(merged.waitTimeout ?? 10000),
+				timeoutMs: merged.timeout !== undefined ? Number(merged.timeout)
+					: hasAnnotate ? 0
+						: runTimeoutMs([...steps, consoleStep], Number(merged.waitTimeout ?? 10000)),
 				log: output.log
 			});
 			result.saved.push(...run.saved);
+			for (const annotation of run.annotations ?? []) {
+				try {
+					await resolveSources(annotation, baseDir);
+				} catch (error) {
+					output.log.error(`annotate: source files not resolved — ${error.message}`);
+				}
+				if (annotation.keys) {
+					try {
+						output.log.info(`annotate keys saved → ${saveAnnotateKeys(annotation.keys)}`);
+					} catch (error) {
+						output.log.error(`annotate: keys not saved — ${error.message}`);
+					}
+				}
+				delete annotation.keys;
+				for (const line of formatAnnotation(annotation)) output.log.info(line);
+				if (annotation.status === "done") {
+					const files = writeAnnotationReport({ annotation, out, prefix: sizes.length > 1 ? `${prefix}${size}-` : prefix, engine, url, baseUrl: merged.baseUrl, size: parseSize(size) });
+					output.log.info(`  → ${files.json}`);
+					output.log.info(`  → ${files.markdown}`);
+					result.annotations.push(files.report);
+				} else result.annotations.push(annotation);
+			}
 			for (const film of run.films ?? []) {
 				try {
 					output.log.info(stitchFilm(film, snapMargin));

package/src/page/annotate/dom.mjs

@@ -0,0 +1,44 @@
+export function pageDom() {
+	const SVG = "http://www.w3.org/2000/svg";
+	const TOKEN = /<\/([\w-]+)\s*>|<([\w-]+)((?:\s+[\w:-]+(?:\s*=\s*(?:"[^"]*"|'[^']*'))?)*)\s*(\/?)>|([^<]+)/g;
+	const ATTRIBUTE = /([\w:-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+	const VOID = new Set(["br", "hr", "img", "input", "link", "meta"]);
+	const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: "\"", "#39": "'" }
+	const decode = text => text.replace(/&(amp|lt|gt|quot|#39);/g, (_, name) => ENTITIES[name]);
+
+	const fragment = markup => {
+		const root = document.createDocumentFragment();
+		const stack = [root];
+		for (const [, closing, tag, attributes, selfClosing, text] of markup.matchAll(TOKEN)) {
+			const parent = stack.at(-1);
+			if (closing) {
+				if (stack.length > 1) stack.pop();
+				continue;
+			}
+			if (text !== undefined) {
+				if (text.trim()) parent.append(decode(text));
+				continue;
+			}
+			const isSvg = tag === "svg" || parent.namespaceURI === SVG;
+			const element = isSvg ? document.createElementNS(SVG, tag) : document.createElement(tag);
+			for (const [, name, double, single] of attributes.matchAll(ATTRIBUTE)) element.setAttribute(name, decode(double ?? single ?? ""));
+			parent.append(element);
+			if (!selfClosing && !VOID.has(tag)) stack.push(element);
+		}
+		return root;
+	}
+
+	const adoptStyles = (root, styles) => {
+		try {
+			const sheet = new CSSStyleSheet();
+			sheet.replaceSync(styles);
+			root.adoptedStyleSheets = [sheet];
+		} catch {
+			const style = document.createElement("style");
+			style.textContent = styles;
+			root.append(style);
+		}
+	}
+
+	return { fragment, adoptStyles }
+}

package/src/page/annotate/format.mjs

@@ -0,0 +1,21 @@
+export const formatAnnotation = annotation => {
+	const lines = [];
+	const { name, status, result } = annotation;
+	if (status !== "done" || !result) return [`annotate ${name}: cancelled`];
+	const elementCount = Object.keys(result.elements).length;
+	lines.push(`annotate ${name}: done · ${result.notes.length} note(s) · ${elementCount} element(s)${result.generalNote ? " · 1 general note" : ""}${result.maskedCount ? ` · ${result.maskedCount} private element(s) hidden` : ""}`);
+	for (const note of result.notes) {
+		const targets = note.elements.map(id => {
+			const element = result.elements[id];
+			if (!element) return id;
+			const source = element.component?.source;
+			const where = source ? ` (${source.file}${source.line ? `:${source.line}` : ""})` : "";
+			return element.component?.name ? `${element.component.name} ${element.label}${where}` : `${element.label}${where}`;
+		});
+		const where = targets.length === 1 ? targets[0] : `${targets.length} elements: ${targets.join(", ")}`;
+		lines.push(`  ${note.id}. ${where} — ${note.text || "(no text)"}`);
+		for (const id of note.elements) lines.push(`     ${id}: ${result.elements[id]?.selector}`);
+	}
+	if (result.generalNote) lines.push(`  general: ${result.generalNote}`);
+	return lines;
+}

package/src/page/annotate/icons.mjs

@@ -0,0 +1,12 @@
+const icon = paths => `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`;
+export const ICONS = {
+	grip: icon("<circle cx='5' cy='9' r='1'/><circle cx='12' cy='9' r='1'/><circle cx='19' cy='9' r='1'/><circle cx='5' cy='15' r='1'/><circle cx='12' cy='15' r='1'/><circle cx='19' cy='15' r='1'/>"),
+	open: icon("<rect width='18' height='18' x='3' y='3' rx='2'/><path d='M9 3v18'/><path d='m14 9 3 3-3 3'/>"),
+	close: icon("<rect width='18' height='18' x='3' y='3' rx='2'/><path d='M9 3v18'/><path d='m16 15-3-3 3-3'/>"),
+	pick: icon("<path d='m12 9-8.414 8.414A2 2 0 0 0 3 18.828v1.344a2 2 0 0 1-.586 1.414A2 2 0 0 1 3.828 21h1.344a2 2 0 0 0 1.414-.586L15 12'/><path d='m18 9 .4.4a1 1 0 1 1-3 3l-3.8-3.8a1 1 0 1 1 3-3l.4.4 3.4-3.4a1 1 0 1 1 3 3z'/><path d='m2 22 .414-.414'/>"),
+	freeze: icon("<path d='m10 20-1.25-2.5L6 18'/><path d='M10 4 8.75 6.5 6 6'/><path d='m14 20 1.25-2.5L18 18'/><path d='m14 4 1.25 2.5L18 6'/><path d='m17 21-3-6h-4'/><path d='m17 3-3 6 1.5 3'/><path d='M2 12h6.5L10 9'/><path d='m20 10-1.5 2 1.5 2'/><path d='M22 12h-6.5L14 15'/><path d='m4 10 1.5 2L4 14'/><path d='m7 21 3-6-1.5-3'/><path d='m7 3 3 6h4'/>"),
+	notes: icon("<path d='M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z'/><path d='M7 11h10'/><path d='M7 15h6'/><path d='M7 7h8'/>"),
+	keys: icon("<path d='M10 8h.01'/><path d='M12 12h.01'/><path d='M14 8h.01'/><path d='M16 12h.01'/><path d='M18 8h.01'/><path d='M6 8h.01'/><path d='M7 16h10'/><path d='M8 12h.01'/><rect width='20' height='16' x='2' y='4' rx='2'/>"),
+	done: icon("<path d='M20 6 9 17l-5-5'/>"),
+	cancel: icon("<path d='M18 6 6 18'/><path d='m6 6 12 12'/>")
+}

package/src/page/annotate/index.mjs

@@ -0,0 +1,50 @@
+import { pageDom } from "#src/page/annotate/dom.mjs";
+import { ICONS } from "#src/page/annotate/icons.mjs";
+import { pageKeys } from "#src/page/annotate/keys.mjs";
+import { MARKUP } from "#src/page/annotate/markup.mjs";
+import { annotatePanel } from "#src/page/annotate/panel.mjs";
+import { pageReact } from "#src/page/annotate/react.mjs";
+import { pageSelectors } from "#src/page/annotate/selector.mjs";
+import { STYLES } from "#src/page/annotate/styles.mjs";
+import { pageVue } from "#src/page/annotate/vue.mjs";
+
+export { formatAnnotation } from "#src/page/annotate/format.mjs";
+
+export const ANNOTATE_KEY = "__webviewPreviewAnnotate";
+export const ANNOTATE_POLL_MS = 250;
+export const ANNOTATE_CLEANUP = `window.${ANNOTATE_KEY}?.cleanup?.()`;
+
+export const annotateStart = (name, keys = null, privateSelectors = []) => `(${annotatePanel})(${JSON.stringify({ key: ANNOTATE_KEY, name, markup: MARKUP, styles: STYLES, icons: ICONS })}, {
+	keys: (${pageKeys})(${JSON.stringify(keys)}),
+	selectors: (${pageSelectors})(${JSON.stringify(privateSelectors)}),
+	react: (${pageReact})(),
+	vue: (${pageVue})(),
+	dom: (${pageDom})()
+})`;
+
+export const ANNOTATE_CHECK = `(() => {
+	const state = window.${ANNOTATE_KEY};
+	if (!state) return "missing";
+	if (state.status === "open") {
+		const draft = state.version !== state.sentVersion ? (state.sentVersion = state.version, state.draft()) : null;
+		const captures = state.captures.splice(0);
+		if (captures.length) state.capturing = captures;
+		return draft || captures.length ? JSON.stringify({ status: "open", draft, captures }) : null;
+	}
+	return JSON.stringify({ status: state.status, result: state.result, keys: state.keys });
+})()`;
+
+export const annotateRestore = draft => `window.${ANNOTATE_KEY}Draft = ${JSON.stringify(draft)};`;
+
+export const annotateStep = (name, keys, privateSelectors = []) => ({
+	kind: "annotate",
+	value: name,
+	start: annotateStart(name, keys, privateSelectors),
+	check: ANNOTATE_CHECK,
+	hide: `window.${ANNOTATE_KEY}?.setHidden?.(true)`,
+	show: `window.${ANNOTATE_KEY}?.setHidden?.(false)`,
+	cleanup: ANNOTATE_CLEANUP,
+	dispose: `window.${ANNOTATE_KEY}?.dispose?.()`,
+	restoreKey: `${ANNOTATE_KEY}Draft`,
+	pollMs: ANNOTATE_POLL_MS
+});