visual-feedback 0.1.0 → 0.2.0

package/dist/{widget-CVnusNlY.mjs → widget-B1JDOVI1.mjs}

@@ -10,10 +10,10 @@ function sheet(text) {
 	return result;
 }
 function variables() {
-	return `.vf{--_r:var(--vf-radius,12px);--_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 4px 16px rgb(0 0 0/12%));--_size:var(--vf-trigger-size,36px);--_off:var(--vf-offset,16px);--_z:var(--vf-z,2147483000)}`;
+	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{position:fixed;z-index:var(--_z);box-sizing:border-box;width:var(--_size);height:var(--_size);margin:0;padding:0;display:grid;place-items:center}.trigger[data-y=bottom]{bottom:calc(var(--_off) + env(safe-area-inset-bottom,0px))}.trigger[data-y=top]{top:calc(var(--_off) + env(safe-area-inset-top,0px))}.trigger[data-x=right]{right:calc(var(--_off) + env(safe-area-inset-right,0px))}.trigger[data-x=left]{left:calc(var(--_off) + env(safe-area-inset-left,0px))}.trigger svg{width:55%;height:55%}.capturing,.capturing .backdrop{visibility:hidden}@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}`;
-const THEME = `.trigger{border:1px solid var(--_b);border-radius:50%;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))}:focus-visible{outline:2px solid var(--_f);outline-offset:2px}`;
+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");
@@ -39,6 +39,30 @@ function deepActive() {
 	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() {},
@@ -76,6 +100,7 @@ function createFeedback(options = {}) {
 	let returnFocus = null;
 	let pending;
 	let trigger;
+	let label;
 	let unlisten;
 	function listen(shortcut) {
 		const parts = shortcut.toLowerCase().split("+");
@@ -126,20 +151,45 @@ function createFeedback(options = {}) {
 				trigger.type = "button";
 				trigger.className = "trigger";
 				trigger.setAttribute("part", "trigger");
-				trigger.append(icon());
+				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;
-			trigger.setAttribute("aria-label", options.strings?.trigger ?? "Send feedback");
+			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);
 	}
@@ -172,22 +222,28 @@ function createFeedback(options = {}) {
 		session++;
 		hide(false);
 	}
-	function teardown() {
-		dialog?.unmount();
+	/** 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) {
+	async function show(mine, kept) {
 		returnFocus = deepActive();
-		const stream = requestDisplay();
+		const stream = kept ? void 0 : requestDisplay();
 		try {
-			const [loaded, capture] = await Promise.all([import("./dialog-BTY6FKLo.mjs"), import("./capture-CufRosj3.mjs")]);
+			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 = await grab(capture, mine, stream);
+			const image = kept ? null : await grab(capture, mine, stream);
 			if (mine !== session) return;
 			if (!host.isConnected) {
 				state = "idle";
@@ -200,9 +256,23 @@ function createFeedback(options = {}) {
 					emit("error", error);
 				}),
 				emit,
-				options: () => options
+				options: () => options,
+				keeps
 			}, options);
-			dialog.capture(image);
+			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) {
@@ -226,19 +296,18 @@ function createFeedback(options = {}) {
 	}
 	const widget = {
 		open() {
-			if (state === "opening" && pending) return pending;
-			if (state !== "idle") return Promise.resolve();
+			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() {
-			if (state !== "open" && state !== "opening") return;
-			const wasOpen = state === "open";
-			state = "idle";
-			cancel();
-			teardown();
-			if (wasOpen) emit("close");
+			end();
 		},
 		destroy() {
 			if (state === "destroyed") return;
@@ -246,8 +315,7 @@ function createFeedback(options = {}) {
 			state = "destroyed";
 			cancel();
 			unlisten?.();
-			if (wasOpen) teardown();
-			const closers = wasOpen ? [...handlers.get("close") ?? []] : [];
+			const closers = wasOpen && !teardown(true) ? [...handlers.get("close") ?? []] : [];
 			handlers.clear();
 			host.remove();
 			call(closers, []);
@@ -269,10 +337,19 @@ function createFeedback(options = {}) {
 			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) widget.close();
+		if (!host.isConnected) end(true);
 	});
 	return widget;
 }
 //#endregion
-export { createFeedback as t };
+export { discardDraft as n, createFeedback as t };

package/dist/{widget-Ca1heF8n.d.mts → widget-Z1KOUKjx.d.mts}

@@ -1,5 +1,5 @@
 
-import { n as Mark, t as FeedbackReport } from "./report-CIgy7uzP.mjs";
+import { n as Mark, t as FeedbackReport } from "./report-CaJegYyg.mjs";
 //#region src/capture.d.ts
 type CaptureOptions = {
   mode?: "dom" | "display";
@@ -8,6 +8,9 @@ type CaptureOptions = {
   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 = {
@@ -16,16 +19,17 @@ type FeedbackEvents = {
   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" | "undo" | "clear" | "cancel" | "send" | "sending" | "sent" | "error" | "retry", string>;
+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?: Mark["tool"][];
+  tools?: Tool[];
   categories?: {
     id: string;
     label: string;
@@ -42,6 +46,7 @@ type FeedbackOptions = {
   unstyled?: boolean;
   container?: HTMLElement;
   tagName?: string;
+  draft?: "session" | "memory";
 };
 type FeedbackWidget = {
   open(): Promise<void>;
@@ -51,6 +56,11 @@ type FeedbackWidget = {
   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, FeedbackStrings as i, FeedbackEvents as n, createFeedback as o, FeedbackOptions as r, CaptureOptions as s, FeedbackEvent as t };
+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

@@ -5,11 +5,13 @@ needs a bundler, or an import map that points that name to the file. There are t
 
 | import | for | runs in |
 |---|---|---|
-| `visual-feedback` | `createFeedback()` and the types | browser |
+| `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";
@@ -17,10 +19,11 @@ import { createFeedback } from "visual-feedback";
 const feedback = createFeedback({
   onSubmit: async (report) => {
     const body = new FormData();
-    body.append("report", JSON.stringify({ ...report, image: undefined }));
-    if (report.image) {
-      const extension = report.image.type === "image/png" ? "png" : "webp";
-      body.append("image", report.image, `${report.id}.${extension}`);
+    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.");
@@ -32,45 +35,55 @@ const feedback = createFeedback({
 | 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, no image) and an `image` part named `<id>.webp` or `<id>.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. |
-| `headers` | `Record<string, string>` or `() => Record<string, string>` | – | Extra headers for `endpoint`. |
-| `trigger` | `"button" \| "none"` | `"button"` | `"none"` draws nothing; the host calls `open()`. |
+| `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 widget is open. 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")[]` | all three | Order is the toolbar order. Repeats and unknown names are ignored; an empty list shows no toolbar. |
+| `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`. |
+| `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. 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 it is already open, it does nothing. When the dialog cannot load or be shown, it rejects and `error` fires. |
-| `close(): void` | Cancels and discards the draft. 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). If the dialog is open, `close` fires, and it is the last event: a delivery still under way fires neither `sent` nor `error`. |
-| `on(event, fn): () => void` | Events: `open`, `close`, `submit` (with the report, before each attempt), `sent` (with the report), `error` (with the error). 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`, `theme`, `css`, `unstyled`, `strings.trigger` 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. |
+| `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
+  createdAt: string;                // ISO 8601, as Date.prototype.toISOString() writes it
   note: string;
-  category?: string;
-  image: Blob | null;               // marks painted in; null after "Send without screenshot"
-  marks: Mark[];                    // vectors, in image pixels
+  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 };
@@ -79,16 +92,26 @@ type FeedbackReport = {
   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] };
+  | { 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. It is a
+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.
@@ -101,19 +124,24 @@ import { Feedback } from "visual-feedback/react";
 
 ## parseFeedbackRequest(request, limits?) (`visual-feedback/server`)
 ```ts
-const { report, image } = await parseFeedbackRequest(request, { maxImageBytes: 5_000_000 });
+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. Fields that `FeedbackReport`
+  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.
-- It checks that the image is a real WebP or PNG (magic bytes, not the declared type) and within
+- 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 `maxImageBytes` plus 1 MiB plus 64 KiB for the multipart framing; a
-  larger body is refused while it streams in.
-- `image` is the checked image, typed from its bytes, or `null` when there is no image part.
-  `report.image` is the same value.
-- If any check fails, it throws a `FeedbackRequestError` that carries a `status` (400 or 413).
+  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.