webview-preview 1.1.2 → 1.2.0

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 = {
@@ -217,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):
@@ -246,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
@@ -256,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):
@@ -325,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()
@@ -340,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":
@@ -398,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)
 
@@ -405,6 +481,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)

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[] }
 	failOnError?: boolean;
 }
 
@@ -89,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[];
@@ -97,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

@@ -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,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,15 +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
-					? runTimeoutMs([...steps, consoleStep], Number(merged.waitTimeout ?? 10000))
-					: Number(merged.timeout),
+				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
+});

package/src/page/annotate/keys.mjs

@@ -0,0 +1,33 @@
+export function pageKeys(saved) {
+	const DEFAULT_KEYS = { pick: "p", notes: "n", freeze: "f", toggle: "t", parent: "ArrowUp", child: "ArrowDown", done: "Control+Enter" }
+	const KEY_ACTIONS = [
+		["pick", "Pick elements"],
+		["notes", "Show / hide notes"],
+		["freeze", "Freeze"],
+		["toggle", "Show / hide tools"],
+		["parent", "Outline the parent"],
+		["child", "Back to the child"],
+		["done", "Done"]
+	];
+	const bindings = { ...DEFAULT_KEYS, ...(saved ?? {}) }
+
+	const KEY_NAMES = { Control: "Ctrl", ArrowUp: "↑", ArrowDown: "↓", ArrowLeft: "←", ArrowRight: "→", " ": "Space" }
+	const showKey = combo => combo.split("+").map(part => KEY_NAMES[part] ?? (part.length === 1 ? part.toUpperCase() : part)).join("+");
+	const comboOf = event => {
+		if (["Control", "Alt", "Shift", "Meta"].includes(event.key)) return null;
+		const parts = [];
+		if (event.ctrlKey) parts.push("Control");
+		if (event.altKey) parts.push("Alt");
+		const code = event.code ?? "";
+		const key = /^Key[A-Z]$/.test(code) ? code.slice(3).toLowerCase()
+			: /^Digit\d$/.test(code) ? code.slice(5)
+				: event.key.length === 1 ? event.key.toLowerCase() : event.key;
+		if (event.shiftKey && key.length > 1) parts.push("Shift");
+		if (event.metaKey) parts.push("Meta");
+		parts.push(key);
+		return parts.join("+");
+	}
+
+	const actionFor = combo => Object.keys(bindings).find(action => bindings[action] === combo) ?? null;
+	return { DEFAULT_KEYS, KEY_ACTIONS, bindings, showKey, comboOf, actionFor }
+}

package/src/page/annotate/markup.mjs

@@ -0,0 +1,37 @@
+import { ICONS } from "#src/page/annotate/icons.mjs";
+
+export const MARKUP = `
+	<div class="layer">
+		<div class="masks"></div>
+		<div class="picks"></div>
+		<div class="outline"><div class="outline-label"></div></div>
+	</div>
+	<div class="dock" role="toolbar" aria-label="webview-preview annotate">
+		<div class="card toolbar">
+			<div class="grip" aria-hidden="true">${ICONS.grip}</div>
+			<button type="button" class="tool toggle" data-action="toggle"></button>
+			<div class="collapse"><div><div class="tools">
+				<button type="button" class="tool pick" data-action="pick" data-tip="Pick elements">${ICONS.pick}</button>
+				<button type="button" class="tool notes-button" data-action="notes" data-tip="Notes">${ICONS.notes}<span class="badge"></span></button>
+				<button type="button" class="tool freeze" data-action="freeze" data-tip="Freeze">${ICONS.freeze}<span class="badge freeze-badge"></span></button>
+				<button type="button" class="tool keys" data-tip="Key bindings">${ICONS.keys}</button>
+				<div class="divider"></div>
+				<button type="button" class="tool accent done" data-action="done" data-tip="Done">${ICONS.done}</button>
+				<button type="button" class="tool cancel" data-tip="Cancel">${ICONS.cancel}</button>
+			</div></div></div>
+		</div>
+		<div class="card sheet notes-sheet" hidden>
+			<div class="sheet-head"><b>Notes</b><span class="run-name"></span></div>
+			<p class="privacy"></p>
+			<ol class="notes"></ol>
+			<label>General note<textarea class="general" rows="2" placeholder="About the whole screen"></textarea></label>
+			<p class="hint"></p>
+		</div>
+		<div class="card sheet keys-sheet" hidden>
+			<div class="sheet-head"><b>Key bindings</b><span>click, then press a key</span></div>
+			<div class="rows"></div>
+			<div class="actions"><button type="button" class="button reset-keys">Reset</button></div>
+		</div>
+	</div>
+	<div class="tip"></div>
+`;