visual-feedback 0.0.0-stage → 0.2.0

package/dist/widget-B1JDOVI1.mjs

@@ -0,0 +1,355 @@
+
+//#region src/widget.ts
+const SVG = "http://www.w3.org/2000/svg";
+function supported() {
+	return typeof document !== "undefined" && "adoptedStyleSheets" in Document.prototype && "adoptedStyleSheets" in ShadowRoot.prototype && CSS.supports("color", "color-mix(in srgb, red, red)");
+}
+function sheet(text) {
+	const result = new CSSStyleSheet();
+	result.replaceSync(text);
+	return result;
+}
+function variables() {
+	return `.vf{--_r:var(--vf-radius,16px);--_s:var(--vf-surface,Canvas);--_t:var(--vf-text,CanvasText);--_m:var(--vf-muted,color-mix(in srgb,var(--_t) 60%,transparent));--_b:var(--vf-border,color-mix(in srgb,var(--_t) 15%,transparent));--_a:var(--vf-accent,${CSS.supports("color", "AccentColor") ? "AccentColor" : "#0b57d0"});--_at:var(--vf-accent-text,#fff);--_f:var(--vf-focus,var(--_a));--_mark:var(--vf-mark,#e5243b);--_bd:var(--vf-backdrop,rgb(0 0 0/45%));--_sh:var(--vf-shadow,0 12px 32px -12px rgb(0 0 0/35%));--_size:var(--vf-trigger-size,2.5em);--_off:var(--vf-offset,16px);--_z:var(--vf-z,2147483000)}`;
+}
+const LAYOUT = `.vf{display:contents;font-family:var(--vf-font,inherit);color-scheme:light dark}.trigger{font:inherit;position:fixed;z-index:var(--_z);box-sizing:border-box;height:var(--_size);margin:0;padding:0 14px 0 12px;display:flex;align-items:center;gap:8px;white-space:nowrap}.trigger[data-icon]{width:var(--_size);padding:0;justify-content:center}[data-y=bottom]{bottom:calc(var(--_off) + env(safe-area-inset-bottom,0px))}[data-y=top]{top:calc(var(--_off) + env(safe-area-inset-top,0px))}[data-x=right]{right:calc(var(--_off) + env(safe-area-inset-right,0px))}[data-x=left]{left:calc(var(--_off) + env(safe-area-inset-left,0px))}.trigger svg{width:1.15em;height:1.15em}.capturing,.capturing .backdrop{visibility:hidden}:focus-visible{outline:2px solid var(--_f);outline-offset:2px}@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}`;
+const THEME = `.trigger{font-weight:600;border:1px solid var(--_b);border-radius:999px;background:var(--_s);color:var(--_t);box-shadow:var(--_sh);cursor:pointer;transition:background-color .15s}.trigger:hover{background:color-mix(in srgb,var(--_s) 90%,var(--_t))}`;
+function icon() {
+	const svg = document.createElementNS(SVG, "svg");
+	const path = document.createElementNS(SVG, "path");
+	for (const [name, value] of Object.entries({
+		viewBox: "0 0 24 24",
+		"aria-hidden": "true",
+		fill: "none",
+		stroke: "currentColor",
+		"stroke-width": "2",
+		"stroke-linejoin": "round",
+		part: "trigger-icon"
+	})) svg.setAttribute(name, value);
+	path.setAttribute("d", "M21 12a8 8 0 0 1-11.6 7.1L4 20l1.1-4.4A8 8 0 1 1 21 12z");
+	svg.append(path);
+	return svg;
+}
+function field(element) {
+	return element.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(element.tagName);
+}
+function deepActive() {
+	let active = document.activeElement;
+	while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+	return active;
+}
+const DISCONNECTED = Symbol.for("visual-feedback.disconnected");
+const owners = /* @__PURE__ */ new Map();
+const enders = /* @__PURE__ */ new WeakMap();
+let dialogs;
+let discarding = Promise.resolve();
+/**
+* Deletes the draft this tab keeps for a tag, as at a logout, so no later widget of the tag brings
+* it back; a widget holding it, open or folded, ends it.
+*/
+async function discardDraft(tagName = "visual-feedback") {
+	const key = `visual-feedback:${tagName}`;
+	let id = null;
+	try {
+		id = sessionStorage.getItem(key);
+		sessionStorage.removeItem(key);
+	} catch {}
+	const owner = owners.get(tagName);
+	if (owner) enders.get(owner)?.();
+	const mine = discarding.then(async () => {
+		await (await dialogs?.catch(() => void 0))?.settled();
+		if (id) await (await import("./keep-BG5WxZPU.mjs")).forget(id);
+	});
+	discarding = mine.catch(() => {});
+	await mine;
+}
+const noop = {
+	open: async () => {},
+	close() {},
+	destroy() {},
+	update() {},
+	on: () => () => {}
+};
+function createFeedback(options = {}) {
+	if (!supported()) return noop;
+	const tag = options.tagName ?? "visual-feedback";
+	if (!customElements.get(tag)) customElements.define(tag, class extends HTMLElement {
+		disconnectedCallback() {
+			this[DISCONNECTED]?.();
+		}
+	});
+	const host = document.createElement(tag);
+	const root = host.attachShadow({ mode: "open" });
+	const wrapper = document.createElement("div");
+	wrapper.className = "vf";
+	root.append(wrapper);
+	let view;
+	const handlers = /* @__PURE__ */ new Map();
+	const call = (fns, args) => {
+		for (const fn of [...fns]) try {
+			fn(...args);
+		} catch (error) {
+			reportError(error);
+		}
+	};
+	const emit = (event, ...args) => call(handlers.get(event) ?? [], args);
+	const start = () => void widget.open().catch(() => {});
+	let state = "idle";
+	let dialog;
+	let session = 0;
+	let returnFocus = null;
+	let pending;
+	let trigger;
+	let label;
+	let unlisten;
+	function listen(shortcut) {
+		const parts = shortcut.toLowerCase().split("+");
+		const key = parts.pop();
+		const names = [
+			"alt",
+			"shift",
+			"control",
+			"meta"
+		];
+		const mods = names.map((name) => parts.includes(name)).join();
+		const typing = !/control|meta/.test(shortcut.toLowerCase());
+		const on = (event) => {
+			if (event instanceof KeyboardEvent && state === "idle" && !event.repeat && !event.isComposing && !event.getModifierState("AltGraph") && parts.every((part) => names.includes(part)) && [
+				event.altKey,
+				event.shiftKey,
+				event.ctrlKey,
+				event.metaKey
+			].join() === mods && [event.code.replace(/^(Key|Digit)/, ""), event.key].some((name) => name.toLowerCase() === key) && !(typing && field(event.composedPath()[0]))) {
+				event.preventDefault();
+				start();
+			}
+		};
+		addEventListener("keydown", on);
+		return () => removeEventListener("keydown", on);
+	}
+	let base = [];
+	let extra = [];
+	function sheets() {
+		const dialogCss = view?.css(Boolean(options.unstyled)).map(sheet) ?? [];
+		root.adoptedStyleSheets = [
+			...base,
+			...dialogCss,
+			...extra
+		];
+	}
+	function apply() {
+		wrapper.style.colorScheme = options.theme?.replace("auto", "") ?? "";
+		base = [sheet(variables() + LAYOUT), ...options.unstyled ? [] : [sheet(THEME)]];
+		extra = options.css ? [sheet(options.css)] : [];
+		sheets();
+		if (options.trigger === "none") {
+			trigger?.remove();
+			trigger = void 0;
+		} else {
+			if (!trigger) {
+				trigger = document.createElement("button");
+				trigger.type = "button";
+				trigger.className = "trigger";
+				trigger.setAttribute("part", "trigger");
+				label = document.createElement("span");
+				label.setAttribute("part", "trigger-text");
+				trigger.append(icon(), label);
+				trigger.addEventListener("click", start);
+				wrapper.prepend(trigger);
+			}
+			const [y, x] = (options.position ?? "bottom-right").split("-");
+			trigger.dataset.y = y;
+			trigger.dataset.x = x;
+			const { trigger: name, triggerText } = options.strings ?? {};
+			trigger.setAttribute("aria-label", name || triggerText || "Send feedback");
+			trigger.toggleAttribute("data-icon", !triggerText);
+			if (label) {
+				label.textContent = triggerText ?? "";
+				label.hidden = !triggerText;
+			}
+		}
+		unlisten?.();
+		unlisten = options.shortcut ? listen(options.shortcut) : void 0;
+	}
+	apply();
+	(options.container ?? document.body ?? document.documentElement).append(host);
+	const keeps = () => {
+		if (options.draft === "memory") return false;
+		if (!owners.get(tag)?.isConnected && host.isConnected) owners.set(tag, host);
+		return owners.get(tag) === host;
+	};
+	restore();
+	function restore() {
+		try {
+			if (!keeps() || !sessionStorage.getItem(`visual-feedback:${tag}`)) return false;
+		} catch {
+			return false;
+		}
+		state = "opening";
+		pending = show(++session, true);
+		pending.catch(() => {});
+		return true;
+	}
+	function hide(on) {
+		wrapper.classList.toggle("capturing", on);
+	}
+	function requestDisplay() {
+		const media = navigator.mediaDevices;
+		if (options.capture?.mode !== "display" || typeof media?.getDisplayMedia !== "function") return;
+		hide(true);
+		const stream = media.getDisplayMedia({ video: true });
+		stream.catch(() => {});
+		return stream;
+	}
+	function stop(stream) {
+		stream?.then((media) => {
+			for (const track of media.getTracks()) track.stop();
+		}, () => {});
+	}
+	async function grab(module, mine, stream) {
+		hide(true);
+		const quiet = view?.announce(root, options.strings);
+		try {
+			return await module.capture(options.capture, stream);
+		} catch {
+			return null;
+		} finally {
+			quiet?.();
+			if (mine === session) hide(false);
+		}
+	}
+	function cancel() {
+		session++;
+		hide(false);
+	}
+	/** Returns whether the draft stays kept; when not, it has ended. */
+	function teardown(keep) {
+		const stays = dialog?.unmount(keep) ?? false;
+		dialog = void 0;
+		const target = returnFocus?.isConnected && returnFocus !== document.body ? returnFocus : trigger;
+		returnFocus = null;
+		target?.focus?.();
+		return stays;
+	}
+	async function show(mine, kept) {
+		returnFocus = deepActive();
+		const stream = kept ? void 0 : requestDisplay();
+		try {
+			dialogs ??= import("./dialog-B57CJ4I_.mjs").catch((error) => {
+				dialogs = void 0;
+				throw error;
+			});
+			const [loaded, capture] = await Promise.all([dialogs, import("./capture-CufRosj3.mjs")]);
+			if (mine !== session) return stop(stream);
+			view = loaded;
+			sheets();
+			const image = kept ? null : await grab(capture, mine, stream);
+			if (mine !== session) return;
+			if (!host.isConnected) {
+				state = "idle";
+				return;
+			}
+			dialog = view.mount(wrapper, {
+				close: () => widget.close(),
+				retry: () => void retry(capture).catch((error) => {
+					widget.close();
+					emit("error", error);
+				}),
+				emit,
+				options: () => options,
+				keeps
+			}, options);
+			const mounted = dialog;
+			if (!kept) mounted.capture(image);
+			else {
+				const back = await mounted.revive();
+				if (mine !== session) {
+					mounted.unmount(true);
+					return;
+				}
+				if (!back) {
+					state = "idle";
+					mounted.unmount();
+					return;
+				}
+			}
+		} catch (error) {
+			stop(stream);
+			if (mine === session) {
+				state = "idle";
+				hide(false);
+				teardown();
+			}
+			emit("error", error);
+			throw error;
+		}
+		state = "open";
+		emit("open");
+	}
+	async function retry(capture) {
+		if (wrapper.classList.contains("capturing")) return;
+		const mine = session;
+		dialog?.lock(false);
+		const image = await grab(capture, mine, requestDisplay());
+		if (mine !== session) return;
+		dialog?.capture(image);
+	}
+	const widget = {
+		open() {
+			if (state === "opening" && pending) {
+				const mine = session;
+				return pending.then(() => mine === session ? widget.open() : void 0);
+			}
+			if (state !== "idle") return dialog?.reopen(), Promise.resolve();
+			if (restore()) return widget.open();
+			state = "opening";
+			pending = show(++session);
+			return pending;
+		},
+		close() {
+			end();
+		},
+		destroy() {
+			if (state === "destroyed") return;
+			const wasOpen = state === "open";
+			state = "destroyed";
+			cancel();
+			unlisten?.();
+			const closers = wasOpen && !teardown(true) ? [...handlers.get("close") ?? []] : [];
+			handlers.clear();
+			host.remove();
+			call(closers, []);
+		},
+		update(next) {
+			if (state === "destroyed") return;
+			options = {
+				...options,
+				...next
+			};
+			apply();
+		},
+		on(event, fn) {
+			if (state === "destroyed") return () => {};
+			const set = handlers.get(event) ?? /* @__PURE__ */ new Set();
+			handlers.set(event, set);
+			const handler = fn;
+			set.add(handler);
+			return () => set.delete(handler);
+		}
+	};
+	function end(keep) {
+		if (state !== "open" && state !== "opening") return;
+		const wasOpen = state === "open";
+		state = "idle";
+		cancel();
+		const stays = teardown(keep);
+		if (wasOpen && !stays) emit("close");
+	}
+	enders.set(host, () => end());
+	host[DISCONNECTED] = () => queueMicrotask(() => {
+		if (!host.isConnected) end(true);
+	});
+	return widget;
+}
+//#endregion
+export { discardDraft as n, createFeedback as t };

package/dist/widget-Z1KOUKjx.d.mts

@@ -0,0 +1,66 @@
+
+import { n as Mark, t as FeedbackReport } from "./report-CaJegYyg.mjs";
+//#region src/capture.d.ts
+type CaptureOptions = {
+  mode?: "dom" | "display";
+  maxWidth?: number;
+  type?: "image/webp" | "image/png";
+  quality?: number;
+};
+//#endregion
+//#region src/annotate.d.ts
+type Tool = Mark["tool"] | "select";
+//#endregion
+//#region src/widget.d.ts
+/** What each event passes to its handlers. */
+type FeedbackEvents = {
+  open: [];
+  close: [];
+  submit: [report: FeedbackReport];
+  sent: [report: FeedbackReport];
+  error: [error: unknown];
+  saved: [];
+};
+type FeedbackEvent = keyof FeedbackEvents;
+/** The texts the widget shows, by SPEC §12 key. */
+type FeedbackStrings = Record<"trigger" | "title" | "capturing" | "captureError" | "sendWithout" | "noteLabel" | "notePlaceholder" | "noteRequired" | "categoryLabel" | "pen" | "box" | "arrow" | "text" | "select" | "remove" | "undo" | "clear" | "cancel" | "send" | "sending" | "sent" | "error" | "retry" | "triggerText" | "escHint" | "minimise" | "screenshot" | "addScreenshot" | "removeScreenshot" | "draft" | "captureView" | "reopen" | "discard" | "discardConfirm" | "keepEditing" | "moreSend" | "savePdf" | "pdfError", string>;
+type FeedbackOptions = {
+  onSubmit?: (report: FeedbackReport) => Promise<void>;
+  endpoint?: string;
+  headers?: Record<string, string> | (() => Record<string, string>);
+  capture?: CaptureOptions;
+  tools?: Tool[];
+  categories?: {
+    id: string;
+    label: string;
+  }[];
+  requireNote?: boolean;
+  redactUrl?: boolean;
+  context?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+  trigger?: "button" | "none";
+  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+  shortcut?: string | false;
+  strings?: Partial<FeedbackStrings>;
+  theme?: "auto" | "light" | "dark";
+  css?: string;
+  unstyled?: boolean;
+  container?: HTMLElement;
+  tagName?: string;
+  draft?: "session" | "memory";
+};
+type FeedbackWidget = {
+  open(): Promise<void>;
+  close(): void;
+  destroy(): void;
+  /** A key given as undefined goes back to its default. */
+  update(options: { [K in keyof FeedbackOptions]?: FeedbackOptions[K] | undefined; }): void;
+  on<E extends FeedbackEvent>(event: E, fn: (...args: FeedbackEvents[E]) => void): () => void;
+};
+/**
+ * Deletes the draft this tab keeps for a tag, as at a logout, so no later widget of the tag brings
+ * it back; a widget holding it, open or folded, ends it.
+ */
+declare function discardDraft(tagName?: string): Promise<void>;
+declare function createFeedback(options?: FeedbackOptions): FeedbackWidget;
+//#endregion
+export { FeedbackWidget as a, CaptureOptions as c, FeedbackStrings as i, FeedbackEvents as n, createFeedback as o, FeedbackOptions as r, discardDraft as s, FeedbackEvent as t };

package/docs/API.md

@@ -0,0 +1,147 @@
+# visual-feedback: API
+
+ESM only, with TypeScript types. On first open it imports `@zumer/snapdom` by name, so a page
+needs a bundler, or an import map that points that name to the file. There are three entry points:
+
+| import | for | runs in |
+|---|---|---|
+| `visual-feedback` | `createFeedback()`, `discardDraft()` and the types | browser |
+| `visual-feedback/server` | `parseFeedbackRequest()`, `FeedbackRequestError` and the report types | any runtime with Web `Request` (Node 20+, Bun, Deno, edge) |
+| `visual-feedback/react` | `<Feedback />` and the type `FeedbackProps` | browser, React 18+ |
+
+## createFeedback(options: FeedbackOptions): FeedbackWidget
+Without a document (a server render) or in a browser below SPEC §10, it returns a widget whose
+methods do nothing: it draws nothing and fires no event.
+
+```ts
+import { createFeedback } from "visual-feedback";
+
+const feedback = createFeedback({
+  onSubmit: async (report) => {
+    const body = new FormData();
+    const screenshots = report.screenshots.map(({ image: _, ...shot }) => shot);
+    body.append("report", JSON.stringify({ ...report, screenshots }));
+    for (const [i, { image }] of report.screenshots.entries()) {
+      const extension = image.type === "image/png" ? "png" : "webp";
+      body.append(`image${i}`, image, `${report.id}-${i}.${extension}`);
+    }
+    const res = await fetch("/api/feedback", { method: "POST", body });
+    if (!res.ok) throw new Error("It didn't send. Your note is kept.");
+  },
+});
+```
+
+### Options
+| option | type | default | meaning |
+|---|---|---|---|
+| `onSubmit` | `(report) => Promise<void>` | – | Sends the report. A throw shows the send error state, using the error's message. Give this or `endpoint`; with both, `onSubmit` is used. |
+| `endpoint` | `string` | – | POSTs `multipart/form-data` with a `report` part (JSON, each screenshot without its image) and one part per screenshot, `image0`, `image1` and on, named `<id>-<n>.webp` or `<id>-<n>.png`. An answer that is not 2xx, a redirect included, shows the send error state with the default `error` text. It is a same-origin `fetch`, so it sends cookies only to the page's own origin; another origin needs CORS on its server and a `connect-src` that allows it. |
+| `headers` | `Record<string, string>` or `() => Record<string, string>` | – | Extra headers for `endpoint`. A function is called at Send; a throw shows the send error state, using the error's message. |
+| `trigger` | `"button" \| "none"` | `"button"` | `"none"` draws no trigger; the host calls `open()`. A kept draft's bar still shows. |
+| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Corner of the trigger. |
+| `shortcut` | `string \| false` | `false` | For example `"Alt+Shift+F"`: any of `Alt`, `Shift`, `Control` and `Meta`, then one key, a letter, a digit or a key name such as `F2`, joined by `+`. The modifiers must match exactly, AltGr never matches, and any other modifier name makes it match nothing. Without `Control` or `Meta` it does not fire while focus is in a text field. It does nothing while the dialog is open or a draft is kept in the draft bar. Opt-in; it is the widget's only global listener, one `keydown` on `window` (SPEC §9 names what the capture library keeps). |
+| `tools` | `("pen" \| "box" \| "arrow" \| "text" \| "select")[]` | all five | Order is the toolbar order, and the first drawing tool is the one selected at open. Repeats and unknown names are ignored; an empty list, or Select alone, shows no toolbar. The Delete button is there only with Select. |
+| `categories` | `{ id: string; label: string }[]` | none | Shows a category picker. |
+| `requireNote` | `boolean` | `true` | |
+| `capture.mode` | `"dom" \| "display"` | `"dom"` | SPEC §5. The type of `capture` is exported as `CaptureOptions`. |
+| `capture.maxWidth` | `number` | `1920` | |
+| `capture.type` | `"image/webp" \| "image/png"` | `"image/webp"` | |
+| `capture.quality` | `number` | `0.85` | For WebP. |
+| `redactUrl` | `boolean` | `false` | Drops the query string and the hash from `page.url`, the report's and each screenshot's. |
+| `context` | `() => Record<string, unknown> \| Promise<…>` | – | Host data added to the report, such as a user id or the app version. Called at Send; a throw shows the send error state, using the error's message. |
+| `strings` | `Partial<FeedbackStrings>` | English | SPEC §12 keys. Keys left out, or given as `undefined`, keep their English text. |
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | THEMING.md. |
+| `css` | `string` | – | Extra CSS added inside the shadow root, after the defaults. THEMING.md. |
+| `unstyled` | `boolean` | `false` | Keeps only the layout-critical CSS and the focus ring. THEMING.md. |
+| `container` | `HTMLElement` | `document.body` | Where the host element is appended. |
+| `tagName` | `string` | `"visual-feedback"` | The custom element name, if it clashes. |
+| `draft` | `"session" \| "memory"` | `"session"` | Where a draft folded in the draft bar is kept. `"session"` keeps it for this tab across page loads and route changes, as it was last folded, until it ends or a day after it was last folded or brought back (SPEC §7); `"memory"` keeps nothing on the device, so a page load ends it. One widget of a tag keeps a draft, the first whose element is in the page; when that element leaves, the next widget of the tag to need it takes over. Another one with the same `tagName` keeps its own in memory only. |
+
+### FeedbackWidget
+| member | meaning |
+|---|---|
+| `open(): Promise<void>` | Starts a capture. When a draft is kept in the draft bar, or this tab still keeps one, it opens the dialog on that draft instead, once it is back; when the dialog is open already, it does nothing. When the dialog cannot load or be shown, it rejects and `error` fires. |
+| `close(): void` | Cancels and discards the draft, also when it is kept in the draft bar, and never asks first as the Cancel button can (SPEC §2); one a page load is still bringing back is only hidden, kept, with no event (SPEC §7). Before `submit` fires, nothing is sent; after it, the delivery is not stopped, and `sent` or `error` still fires when it ends. |
+| `destroy(): void` | Removes the element, its listeners and its stylesheet, but not what the capture library keeps (SPEC §9). A delivery still under way fires neither `sent` nor `error` after it. The draft, open or folded, stays kept, so `close` does not fire: the next widget of the same tag made in this tab brings it back folded, as after a page load, so a route change keeps it. A host that removes the element gets the same. A draft it cannot keep ends, and `close` fires as the last event: with `draft: "memory"`, a Send already handed to the host (`submit` fired), a widget that does not own its tag's draft, no screenshot (the capture error, or after "Send without screenshot"), a screenshot taken while it did not keep drafts, or sessionStorage that refuses it. To end the draft too, as at a logout, call `discardDraft()`. A draft whose IndexedDB write then fails (storage full) is lost, with no `close`: the widget is gone by then. |
+| `on(event, fn): () => void` | Events: `open` (when a draft starts, and when a kept draft comes back), `close` (only when the draft ends: sent and closed, Cancel, Discard, `close()`, or a `destroy()` or removed element that does not keep it; folding into the draft bar, opening it again, and a `destroy()` or removal that keeps it fire none), `submit` (with the report, before each attempt), `sent` (with the report), `error` (with the error), `saved` (after Save as PDF downloads the PDF; nothing is sent). The type `FeedbackEvents` maps each event to what it passes. Returns an unsubscribe function. |
+| `update(options): void` | Merges these options into the current ones, key by key: a key given as `undefined` goes back to its default, and `strings` or `capture` replaces the whole object. `tagName` and `container` are ignored. The trigger, `position` (a draft bar already shown moves at its next fold), `theme`, `css`, `unstyled`, `strings.trigger`, `strings.triggerText` and `shortcut` change at once. The dialog's texts, `tools`, `categories` and `requireNote` apply from the next open, and the rest at the next capture or send. |
+
+## discardDraft(tagName?: string): Promise<void>
+Deletes the draft this tab keeps for a tag (default `"visual-feedback"`), as at a logout, so no
+later widget of that tag brings it back: the id in sessionStorage and the record in IndexedDB. A
+widget that holds it, open or folded, ends it, and `close` fires; one still bringing it back at a
+page load stops, with no event, since it never showed it. It waits for a write still under
+way, so none lands after it. It needs no widget on the page; with `<Feedback />`, import it from
+`visual-feedback`. A widget made with a `tagName` needs that same name here. It rejects when the
+device's storage cannot be reached; the id is already gone by then, so no widget brings the draft
+back.
+
+## FeedbackReport
+```ts
+type FeedbackReport = {
+  id: string;                       // UUID v4 from crypto.getRandomValues, so plain http works
+  createdAt: string;                // ISO 8601, as Date.prototype.toISOString() writes it
+  note: string;
+  category?: string;                // the chosen category's id; absent without `categories`
+  screenshots: Screenshot[];        // at most 10; empty after "Send without screenshot"
+  page: { url: string; title: string };
+  viewport: { width: number; height: number; devicePixelRatio: number };
+  scroll: { x: number; y: number };
+  userAgent: string;
+  language: string;
+  timeZone: string;
+  context: Record<string, unknown>;
+};
+type Screenshot = {
+  image: Blob;                      // marks painted in
+  marks: Mark[];                    // shapes and text labels, in image pixels
+  page: { url: string; title: string };  // the page as it was when this screenshot was taken
+  viewport: { width: number; height: number; devicePixelRatio: number };
+  scroll: { x: number; y: number };
+};
+type Mark =
+  | { tool: "pen"; points: [number, number][] }
+  | { tool: "box"; x: number; y: number; width: number; height: number }
+  | { tool: "arrow"; from: [number, number]; to: [number, number] }
+  // A label, its text at most 280 characters, centred on y and starting at x.
+  | { tool: "text"; x: number; y: number; text: string };
+```
+
+## `<Feedback {...options} />` (`visual-feedback/react`)
+Its props are the options of `createFeedback`. It renders nothing where it stands: after it mounts
+in the browser it creates the widget, a changed prop goes to `update()` (a prop that is gone goes
+back to its default; `tagName` and `container` are read once), and unmounting destroys it, which
+keeps a draft: call `discardDraft()` at a logout. It is a
+client component, so a server component can render it with props that reach the browser as data,
+such as `endpoint`; `onSubmit`, `headers` as a function, `context` and `container` need a client
+component.
+
+```tsx
+import { Feedback } from "visual-feedback/react";
+
+<Feedback endpoint="/api/feedback" />;
+```
+
+## parseFeedbackRequest(request, limits?) (`visual-feedback/server`)
+```ts
+const { report } = await parseFeedbackRequest(request, { maxImageBytes: 5_000_000 });
+```
+- It reads the multipart body that `endpoint` sends and checks the report's shape. `id` must be a
+  lower-case UUID v4, and `createdAt` an ISO time from 1970 to 9999, in exactly the form
+  `Date.prototype.toISOString()` writes (UTC, with milliseconds). Fields that `FeedbackReport`
+  does not define, and `__proto__` keys at any depth, are dropped.
+- In the report's text, `context` included, NUL characters are removed and half surrogate pairs (a
+  cut emoji) become U+FFFD, so any store, Postgres `jsonb` included, can keep it.
+- A report holds at most 10 screenshots, and screenshot `n` needs exactly one image part,
+  `image<n>`. An image part with no screenshot is refused, and so is a part named `image`, which
+  visual-feedback 0.1 sent.
+- It checks that each image is a real WebP or PNG (magic bytes, not the declared type) and within
+  `maxImageBytes`, which is `10_000_000` by default. The report part may be at most 1 MiB, and
+  the whole body at most 10 times `maxImageBytes` plus 1 MiB plus 64 KiB for the multipart
+  framing; a larger body is refused while it streams in.
+- `report.screenshots[n].image` is the checked image of part `image<n>`, typed from its bytes.
+- If any check fails, it throws a `FeedbackRequestError` that carries a `status` (400 or 413). A
+  `maxImageBytes` that is not a number of bytes is a mistake in the host's code: it throws a
+  `RangeError`.
+- Storing the report, and checking who sent it, is the host's job. `report.context` comes from the
+  browser, so it is never proof of who sent it: take the user from your own session.