webview-preview 1.1.2 → 1.2.1

package/src/engines/playwright.mjs

@@ -19,14 +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, timeoutMs = TIMEOUT_MS, log
+	snapMargin = 8, isHeaded = false, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, onAnnotation, 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 {
@@ -71,8 +72,92 @@ 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 report = annotation => {
+			annotations.push(annotation);
+			onAnnotation?.(annotation);
+		}
+
+		const annotate = async step => {
+			let round = 1;
+			const base = () => `${prefix}annotate-${step.value}${round > 1 ? `-${round}` : ""}`;
+			let images = {}
+			let draft = null;
+			let lastUrl = null;
+			await page.evaluate(step.start);
+			for (;;) {
+				if (page.isClosed()) {
+					report({ name: step.value, status: "cancelled", result: null, round });
+					return;
+				}
+				if (Date.now() > deadline) {
+					report({ name: step.value, status: "cancelled", result: null, round });
+					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") {
+					for (const earlier of step.replay ?? []) {
+						try {
+							await runStep(earlier);
+						} catch (error) {
+							log.error(`replay: ${error.message.split("\n")[0]}`);
+						}
+					}
+					if (lastUrl && page.url() !== lastUrl) {
+						await page.evaluate(`location.href = ${JSON.stringify(lastUrl)}`).catch(() => undefined);
+						await page.waitForTimeout(JS_SETTLE_MS);
+					}
+					await page.evaluate(`${draft ? `window.${step.restoreKey} = ${JSON.stringify(draft)};` : ""}${step.start}`).catch(() => undefined);
+				} else if (answer?.status === "open") {
+					if (answer.url) lastUrl = answer.url;
+					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, round, scale: scale ?? 1 }
+					const isSent = annotation.status === "sent";
+					if ((annotation.status === "done" || isSent) && 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;
+						}
+						if (!isSent) await page.evaluate(step.dispose).catch(() => undefined);
+					}
+					report(annotation);
+					if (!isSent) return;
+					round += 1;
+					images = {}
+					draft = null;
+					await page.evaluate(step.resume).catch(() => undefined);
+				}
+				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;
@@ -133,5 +218,5 @@ export const runPlaywright = async ({
 		await browser.close();
 	}
 
-	return { saved, failed, films }
+	return { saved, failed, films, annotations }
 }

package/src/engines/webkitgtk.mjs

@@ -13,7 +13,7 @@ export const runWebkitGtk = ({
 	url, steps, init = [], size, colorScheme,
 	isMotionReduced = false, out, prefix, snapMargin = 8,
 	isHeaded = false, isStorageKept = false,
-	waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, log
+	waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, onAnnotation, log
 }) => new Promise((resolve, reject) => {
 	if (!isWebkitGtkAvailable()) {
 		reject(new Error("WebKitGTK engine needs Linux with python3-gi and WebKit2 4.1 (gir1.2-webkit2-4.1)"));
@@ -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,10 @@ 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);
+				onAnnotation?.(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 +78,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 = {
@@ -118,6 +119,9 @@ def main():
         return False
 
     def step_failed(message):
+        if state.get("replaying"):
+            emit("error", f"replay: {message}")
+            return
         state["failed"] = True
         emit("error", message)
 
@@ -217,10 +221,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):
@@ -246,7 +251,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
@@ -256,12 +261,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):
@@ -325,6 +334,98 @@ def main():
     def next_step():
         GLib.idle_add(run_step)
 
+    def annotate(step):
+        memory = state.setdefault("annotate_memory", {}).setdefault(
+            step["value"], {"draft": None, "round": 1, "images": {}, "url": None}
+        )
+
+        def base():
+            return f"annotate-{step['value']}" + (f"-{memory['round']}" if memory["round"] > 1 else "")
+
+        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 replay():
+            resume = {**step, "isResume": True}
+            steps[state["index"]:state["index"]] = [*step["replay"], resume]
+            state["replaying"] = True
+            next_step()
+
+        def go_back_then_restart():
+            url = memory["url"]
+            if not url:
+                return restart()
+            code = f"if (location.href !== {json.dumps(url)}) location.href = {json.dumps(url)};"
+            evaluate(code, lambda _: later(restart, args.js_settle_ms), lambda _: restart())
+
+        def grab(captures):
+            def shoot():
+                for capture in captures:
+                    path = crop(f"{base()}-{capture['id']}", capture["rect"], False)
+                    if path:
+                        memory["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):
+            is_sent = answer.get("status") == "sent"
+            if not is_sent:
+                state["annotating"] = None
+            result = answer.get("result")
+            width = view.get_allocated_width()
+            answer.update(name=step["value"], round=memory["round"], scale=full_pixbuf().get_width() / width if width else 1)
+            if answer.get("status") not in ("done", "sent") 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 memory["images"].get(element_id)
+                emit("annotate", answer)
+                if not is_sent:
+                    return evaluate(step["dispose"], lambda _: next_step(), lambda _: next_step())
+                memory.update(draft=None, images={}, round=memory["round"] + 1)
+                evaluate(step["resume"], lambda _: again(), lambda _: again())
+
+            evaluate(step["cleanup"], lambda _: later(crops, ANNOTATE_SETTLE_MS * 2), lambda _: crops())
+
+        def poll():
+            def on_value(text):
+                if text == "missing":
+                    return replay() if step.get("replay") else 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("url"):
+                    memory["url"] = answer["url"]
+                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"]
+        if step.get("isResume"):
+            state["replaying"] = False
+            return go_back_then_restart()
+        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()
@@ -340,6 +441,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":
@@ -398,6 +501,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)
 
@@ -405,6 +510,16 @@ 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)
@@ -414,6 +529,13 @@ def main():
 
     sys.stdout.flush()
     sys.stderr.flush()
+    try:
+        view.terminate_web_process()
+        window.destroy()
+        while Gtk.events_pending():
+            Gtk.main_iteration_do(False)
+    except Exception:
+        pass
     os._exit(1 if state["failed"] else 0)
 
 

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}`
@@ -64,6 +66,7 @@ export interface PreviewConfig {
 	globals?: Record<string, unknown>;
 	locale?: string;
 	macros?: Record<string, Step[] | string[]>;
+	annotate?: { private?: string[]; keepOpen?: boolean }
 	failOnError?: boolean;
 }
 
@@ -89,6 +92,8 @@ export interface MockResponse {
 export type InitEntry = string | { file: string }
 
 export interface PreviewOptions extends PreviewConfig {
+	private?: string | string[];
+	keepOpen?: boolean;
 	target?: string;
 	steps?: Step[] | string[];
 	initFile?: string | string[];
@@ -97,11 +102,57 @@ 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" | "sent" | "cancelled";
+	round: number;
+	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

@@ -12,6 +12,10 @@ 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, 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,34 @@ 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 keepOpen = !!(options.keepOpen ?? config.annotate?.keepOpen);
+	const REPLAYED = new Set(["js", "jsnow", "wait", "waitfor", "key", "type", "hover", "click", "offline", "online", "latency"]);
+	const steps = parsedSteps.map((step, index) => step.kind === "annotate"
+		? {
+			...annotateStep(step.value, savedKeys, privateSelectors, keepOpen),
+			replay: parsedSteps.slice(0, index).filter(earlier => REPLAYED.has(earlier.kind) && !earlier.assert).map(earlier => ({ ...earlier, isReplay: true }))
+		}
+		: step);
 	const out = path.resolve(baseDir, merged.out);
 	const url = resolveUrl(merged.target ?? merged.url ?? "/", merged.baseUrl);
 	const sizes = parseSizes(merged.size);
@@ -112,9 +137,35 @@ 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 reports = [];
+			const handleAnnotation = async annotation => {
+				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" && annotation.status !== "sent") {
+					result.annotations.push(annotation);
+					return;
+				}
+				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);
+			}
 			const run = await runEngine(engine, {
 				url,
 				steps: [...steps, consoleStep],
@@ -127,15 +178,17 @@ 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
-					? runTimeoutMs([...steps, consoleStep], Number(merged.waitTimeout ?? 10000))
-					: Number(merged.timeout),
+				onAnnotation: annotation => reports.push(handleAnnotation(annotation)),
+				timeoutMs: merged.timeout !== undefined ? Number(merged.timeout)
+					: hasAnnotate ? 0
+						: runTimeoutMs([...steps, consoleStep], Number(merged.waitTimeout ?? 10000)),
 				log: output.log
 			});
 			result.saved.push(...run.saved);
+			await Promise.all(reports);
 			for (const film of run.films ?? []) {
 				try {
 					output.log.info(stitchFilm(film, snapMargin));
@@ -166,7 +219,7 @@ export const preview = async (options = {}) => {
 		if (report) baseLog.info(`report → ${report}`);
 		return { engine, url, sizes, ...result, consoleErrors, failedAsserts, report, failed }
 	} finally {
-		stopServer();
+		await stopServer();
 	}
 }
 

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,22 @@
+export const formatAnnotation = annotation => {
+	const lines = [];
+	const { name, status, result } = annotation;
+	if ((status !== "done" && status !== "sent") || !result) return [`annotate ${name}: cancelled`];
+	const elementCount = Object.keys(result.elements).length;
+	const round = annotation.round > 1 || status === "sent" ? ` (round ${annotation.round ?? 1})` : "";
+	lines.push(`annotate ${name}: ${status}${round} · ${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,13 @@
+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'/>"),
+	send: icon("<path d='M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z'/><path d='m21.854 2.147-10.94 10.939'/>"),
+	done: icon("<path d='M20 6 9 17l-5-5'/>"),
+	cancel: icon("<path d='M18 6 6 18'/><path d='m6 6 12 12'/>")
+}