visual-feedback 0.1.0 → 0.3.0

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 form field (`input`, `textarea`, `select`) or editable content. 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 listener on `window` or `document`, one `keydown` on `window` (SPEC §9 names what else the widget watches, and 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, its watch of the page's theme 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 for the draft, but its listeners and its watch of the page's theme stay until `destroy()`. 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, and a new `theme` or `css` reads the page's look again (THEMING.md). 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.

package/docs/SPEC.md

@@ -3,43 +3,88 @@
 ## 1. What it is
 A user reports a problem or an idea from the page they are on. They capture the screen, mark it
 up, write a note and send it. The host app receives one report and decides where it goes. The
-package stores nothing and sends nothing by itself.
+package sends nothing by itself, and stores nothing but an unsent draft on the user's own device
+(§7).
 
 ## 2. Flow
 ```
 idle --open--> capturing --image ready--> annotating --Send--> sending --ok--> sent --3 s--> idle
-                   |                          |                    |
-                   +--fails--> capture error  +--Cancel/Esc--> idle +--fails--> send error
+                   |                          |   ^                |
+                   +--fails--> capture error  |   |                +--fails--> send error
+                                              |   +--Open, or Capture this view (capturing first)
+                                              +--Esc / Keep as draft / Add screenshot--> draft
+annotating, draft --Cancel (it may ask first, below) / Discard--> idle
 ```
 - **idle:** the trigger button shows (`trigger: "button"`), or nothing shows (`trigger: "none"`,
   where the host calls `open()`).
 - **capturing:** the trigger and any open panel are hidden, so they are not in the image. The
   screen is captured (SPEC §5), and a screen reader is told the `capturing` text.
 - **capture error:** the `captureError` text, with "Try again" (back to capturing), "Send without
-  screenshot" (annotating with no image: no toolbar, `image: null`, no marks) and Cancel or Esc
-  (idle).
-- **annotating:** a full-viewport overlay shows the image, a toolbar and the note field.
+  screenshot" (annotating with no image: no toolbar, no screenshots in the report) and Cancel or Esc
+  (idle). This is the first screenshot only; a later one that fails is the draft's (below).
+- **annotating:** a full-viewport overlay shows the image with a tool rail beside it, a strip of
+  the report's screenshots under it, and the note field, with Send in a footer row under that.
+  Esc and the header's Keep as draft fold it into the draft; the header's close button (Cancel)
+  discards it. When that would throw away a note, a mark, a second screenshot or a chosen category,
+  Cancel first asks `discardConfirm`, with "Discard", `minimise` (before Send, with a screenshot) and
+  `keepEditing`, which has the focus; Keep editing, and Esc on the question, take the question back
+  and put the focus on Cancel. Without a screenshot ("Send without screenshot"), Esc cancels,
+  after the same question when it would throw work away.
+- **draft:** a small bar in the trigger's corner, in place of the trigger: the `draft` label with
+  the number of screenshots, small copies of them, "Capture this view", "Open" and "Discard". The
+  page scrolls, and a single-page app can change route, while it shows. "Capture this view" takes
+  another screenshot of the page as it is now, the bar and the dialog left out, adds it, and opens
+  the dialog on it; a capture that fails opens the dialog on the kept draft with the
+  `captureError` text, where Esc keeps the draft again and Cancel discards it, after the same question when it would throw work away. "Open", and `open()`, open the dialog as it was. A full page load in the same tab, or a route
+  change that removes the widget and makes the next one, brings the draft back, folded in the bar, as it was when it was last folded: its screenshots, marks, note and
+  category. Undo starts after the marks it brought back. With `draft: "memory"`, a page load ends
+  it.
 - **sending:** the note, the category and the tools are disabled, and the Send button shows
-  progress. Cancel and Esc still close the dialog.
+  progress. The Esc hint goes, as it is absent with no screenshot: from Send on, Esc keeps no
+  draft, and Cancel and Esc close the dialog.
 - **sent:** a short confirmation, then idle.
 - **send error:** the message comes from the host's error, or else the `error` text. The note and
-  the marks are kept, and "Try again" sends the same report.
+  the marks are kept, and "Try again" sends the same report. Cancel and Esc, after
+  the same question when it would throw work away, close the dialog, and the draft goes with it.
 
 ## 3. The trigger
-- It is a small round button, 36 px by default, in a corner (`position`), with an icon and an
-  accessible name. It has no text label and no badge, and it does not move or pulse.
+- It is a small round button, 2.5em across by default (40 px on a 16 px site), in a corner
+  (`position`), with an icon and the `trigger` accessible name. A host that gives `triggerText`
+  gets that short label beside the icon, as a pill; with only `triggerText` given, that text is
+  the name too. A host that sets both keeps `triggerText` inside `trigger`, so
+  speech control can say what it sees. It has no badge, and it does not move or pulse.
 - It sits 16 px from the edges by default, and it respects `env(safe-area-inset-*)`.
-- It does not watch the page. The host moves it off its own content with `position` or
-  `--vf-offset`.
+- It is hidden while there is a draft, whether the dialog is open or kept in the draft bar.
+- It does not move to keep clear of the page's content. The host moves it off its own content
+  with `position` or `--vf-offset`.
 
 ## 4. Annotating
-- **Tools:** Pen (freehand), Box (rectangle outline) and Arrow. Undo removes the last mark, and
-  Clear removes all.
+- **Tools:** Pen (freehand), Box (rectangle outline), Arrow and Text. Text places a label where the
+  image is clicked: Enter or clicking away keeps it, Escape drops that label only, and an empty one
+  is not kept; a label holds up to 280 characters. Labels are one size, in the mark colour with a white outline. Select picks a mark by
+  its line or a label by its text, and shows a dashed outline that never reaches the sent image: a
+  drag moves it, kept whole inside the image; the arrow keys move it (Shift for ten); Delete,
+  Backspace or the Delete button removes it; Escape lets go of it. Undo takes back the last add,
+  move or removal, one at a time, and Clear removes all.
 - **One colour** for the marks, `--vf-mark`, which defaults to a red that contrasts with most pages.
 - Pointer events, so mouse, pen and touch all work. While drawing, touch never scrolls the page.
 - **Note:** a textarea of 2000 characters at most, with a visible label (`noteLabel`). It is
   required unless `requireNote: false`.
 - **Category:** shown only when `categories` is given, with a visible label (`categoryLabel`).
+- **Save as PDF:** Send is a split button; its caret ("More send options") opens a menu with "Save
+  as PDF". It downloads `feedback-<date>.pdf`, dated by the user's clock and made in the browser:
+  the category and the note,
+  then the first screenshot, on page 1, and each other screenshot on a page of its own, marks
+  included. Nothing is sent, the dialog and the draft stay as they are, and the `saved` event
+  fires. While the menu is open, Esc closes the menu only, from Send and the menu button too, and
+  puts the focus on the menu button; Tab closes it too. A PDF that cannot be made, a page the browser has no memory to draw
+  included (as on iOS), shows the `pdfError` text, never a blank page, and
+  neither `saved` nor `error` fires, since nothing failed to send; one asked for while another is being made is ignored.
+- **Screenshots:** a report holds up to 10. Each keeps its own marks and its own Undo; the tool
+  chosen stays the same across them. The strip numbers them in the order they are sent: a click
+  shows one, and its remove button, there only when there are two or more, takes one out. "Add
+  screenshot" folds the dialog into the draft, and is gone at 10. The note and the category are one
+  for the whole report.
 - Sending without any mark is allowed.
 
 ## 5. Capture
@@ -53,39 +98,73 @@ idle --open--> capturing --image ready--> annotating --Send--> sending --ok--> s
 - **Format:** WebP by default, or PNG if the browser cannot encode WebP.
 - **Fonts and images:** what cannot be drawn (for example a cross-origin image without CORS) shows
   as a grey box. It never makes the capture fail.
+- **Known limit:** in "dom", text cut by `-webkit-line-clamp` with a fractional line height (such as
+  15px at 1.35) shows one line fewer than the page. The cause is in the capture library, snapdom
+  3.3.0; this repository patches its own copy for its tests, which does not reach a host's install.
 
 ## 6. The report
 Defined in `docs/API.md` (`FeedbackReport`). It holds:
-- the flattened image, with the marks painted in, or no image after "Send without screenshot";
-- the marks as vectors;
+- the screenshots, at most 10, or none after "Send without screenshot". Each has its flattened
+  image with the marks painted in, the marks as vectors, and the page URL and title, the viewport
+  and the scroll position as they were when it was taken;
 - the note and the category;
-- the page URL and title, the viewport and the scroll position, as they were at the screenshot;
+- the page URL and title, the viewport and the scroll position, as they were at the first
+  screenshot, or at the capture error after "Send without screenshot";
 - the user agent, the language, the time zone and the time of Send;
 - whatever the host's `context()` returns.
 
 ## 7. Privacy
 - The image is what the user sees. Nothing on the page is masked, hidden or redacted, password
   fields included. Only the widget itself is left out (SPEC §2, capturing).
-- The image is never kept after `close()`.
-- No console logs, network logs, cookies, storage or keystrokes are collected.
+- No screenshot is kept after the draft ends: Send, Cancel, Discard, `close()` or `discardDraft()`.
+- No console logs, network logs, cookies or keystrokes are collected. Nothing is stored, with one
+  exception: a draft folded in the draft bar is kept on this device for this tab, so a page load
+  does not lose it. sessionStorage holds its id, and IndexedDB its screenshots with each one's
+  page facts (the whole URL: `redactUrl` applies only to the sent report), marks, note and category. It is deleted when the draft ends: the moment Send succeeds, or at Cancel, Discard,
+  `close()` or `discardDraft()`, which a host calls at a logout. `destroy()`, or the host removing the element, keeps it, open or folded, for the next
+  widget of that tag in this tab, unless its Send was already handed to the host; a click while
+  this tab keeps one opens 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, and never
+  writes over a draft still kept. Any other keeps its own in memory.
+  A `close()` made while a page load is still bringing it back hides it on
+  that page and keeps it. A day after it was last folded or brought back, it no longer comes back,
+  and it is deleted the next time this site opens the dialog or keeps a draft, in any tab: nothing
+  of the widget runs on the device to delete it sooner. A tab the browser duplicates copies
+  sessionStorage, so the copy shares that draft. `draft: "memory"` keeps
+  it in memory only, and does not delete one an earlier page kept.
 - The query string and the hash of the URL are kept unless `redactUrl: true` is set.
 
 ## 8. Accessibility
 - The overlay is a `role="dialog"` with `aria-modal="true"` and a label.
-- Focus stays inside the dialog, and Escape cancels it. While it is open, the page does not
-  scroll. On close, focus goes back to the trigger, or to where it was before.
-- Every control has an accessible name and a visible focus ring (`--vf-focus`).
+- Focus stays inside the dialog. Escape, except on the Send menu, a label being typed or a selected
+  mark (§4), or on Cancel's question (§2),
+  keeps an unsent draft that has a screenshot in the draft bar, and moves the focus to it ("Capture
+  this view", or "Open" at 10 screenshots). With no screenshot, or after a send error, it cancels,
+  asking first as Cancel does; while sending, and once sent, it closes at once.
+  While the dialog is open, the page does not scroll. On close, focus goes back to the trigger,
+  or to where it was before.
+- Every control has an accessible name and a visible focus ring (`--vf-focus`), `unstyled`
+  included (THEMING.md).
 - With the keyboard alone, the user can still write the note, choose a category and send without
   marks.
 - `prefers-reduced-motion` turns off every transition.
-- `prefers-color-scheme` sets the default theme (`theme: "auto"`).
+- With `theme: "auto"`, the page's own background sets light or dark, and `prefers-color-scheme`
+  where the page shows none (THEMING.md).
 
 ## 9. Budgets
-- **Loader** (the trigger and the `open()` wiring): 3 KB or less, minified and gzipped.
-- **Annotator and dialog:** 15 KB or less, gzipped. This does not include the capture library.
-- **Idle cost:** no work after the first paint of the trigger. After the first screenshot, the
+- **Loader** (the trigger and the `open()` wiring): 15 KB or less, minified and gzipped.
+- **Annotator and dialog:** 135 KB or less, gzipped. This does not include the capture library.
+- **Idle cost:** no work after the first paint of the trigger, past reading one sessionStorage
+  key and the page's colours and button corners at load, and reading them again when the page
+  switches its theme (THEMING.md section 1). To see a switch, it keeps one mutation observer on
+  the attributes of `<html>` and `<body>` and on the children of `<html>` (to find a new
+  `<body>`), and one `change` listener on `prefers-color-scheme`, both gone at `destroy()`. A
+  change the observer sees that leaves the page's colours alone reads the colours of `<html>` and
+  `<body>` and scans nothing else; a system switch always reads the page. Only when this tab kept a draft does the dialog load, to bring it back. After the first screenshot, the
   capture library (snapdom) keeps 12 listeners on `window` and `document` and up to 5 mutation observers
-  until the page unloads, and offers no way to remove them; `destroy()` removes everything else.
+  until the page unloads, and offers no way to remove them; `destroy()` removes everything else
+  but a draft it keeps (§7). The opt-in `shortcut` adds one `keydown` listener on `window`, gone at
+  `destroy()` or `update({ shortcut: false })`.
 - CI fails when a budget is exceeded.
 
 ## 10. Browsers
@@ -93,8 +172,9 @@ The browsers that support constructable stylesheets (`adoptedStyleSheets`) and `
 Chrome 111+, Firefox 113+ and Safari 16.4+. Older browsers get no trigger and no error.
 
 ## 11. Content Security Policy
-- The widget's own CSS goes in through constructable stylesheets. It uses no `<style>` tags and
-  no inline `style` attributes, so a strict `style-src` does not block it. While the dialog is
+- The widget's own CSS goes in through constructable stylesheets. It uses no `<style>` tags, and
+  sets the few inline styles it needs (the selection frame, a label being typed, the theme's
+  `color-scheme` and the colours and corners it found on the page) through the CSSOM, so a strict `style-src` does not block it. While the dialog is
   open, the scroll lock sets `overflow` on `<html>` through the CSSOM, which a CSP allows, and
   puts back what was there on close.
 - Capture (`@zumer/snapdom`) renders through `data:` image URLs, so a site with a CSP needs
@@ -119,10 +199,22 @@ These are the default texts. Each one can be replaced through `strings` (`docs/A
 | notePlaceholder | What happened, or what would you change? |
 | noteRequired | Write a few words first. |
 | categoryLabel | Type |
-| pen / box / arrow | Draw / Box / Arrow |
+| pen / box / arrow / text / select | Draw / Box / Arrow / Text / Select |
+| remove | Delete |
 | undo / clear | Undo / Clear |
 | cancel / send | Cancel / Send |
 | sending | Sending… |
 | sent | Thanks, it's sent. |
 | error | It didn't send. Your note is kept. |
 | retry | Try again |
+| triggerText | none: the icon alone |
+| escHint | Esc keeps it as a draft |
+| minimise | Keep as draft |
+| screenshot | Screenshot (each one is named with its number, as "Screenshot 2") |
+| addScreenshot | Add screenshot |
+| removeScreenshot | Remove screenshot (with the number, as "Remove screenshot 2") |
+| draft | Feedback draft (the bar shows the number of screenshots after it) |
+| captureView / reopen / discard | Capture this view / Open / Discard |
+| discardConfirm / keepEditing | Discard this feedback? / Keep editing |
+| moreSend / savePdf | More send options / Save as PDF |
+| pdfError | Couldn't save the PDF. |

package/docs/THEMING.md

@@ -3,11 +3,34 @@
 The widget lives in one shadow root, so the site's CSS cannot break it, and its CSS cannot leak
 out. There are four ways to adapt it, from lightest to heaviest:
 
-## 1. It inherits
-Inside the shadow root, the widget sets `font: inherit` and `color-scheme: light dark`, so a site
-rule such as `* { all: unset }` cannot reset them. The defaults use the system colours `Canvas`,
-`CanvasText` and `AccentColor`. With no theming at all, it takes the site's font and follows light
-and dark mode.
+## 1. It matches the site
+Inside the shadow root, the widget sets `font: inherit`, so a site rule such as
+`* { all: unset }` cannot reset it. With no theming at all, it takes the site's font, and it
+reads the page when it loads, at each open (a draft opened again from its bar too), when
+`theme` or `css` changes, and when the page switches its theme: a change to the attributes of `<html>` or
+`<body>`, such as a `dark` class, that changes the page's background, text colour or
+`color-scheme`, or a change of the system's light or dark. The trigger, the dialog and the draft
+bar then take the new look at once, or, where the site fades its colours, when the fade ends. A
+widget whose element was off the page reads the page again when the element is put back. The rest
+of the page is not watched, so a look changed only by a new stylesheet shows at the next open.
+What it reads:
+
+- **accent:** the page's `<meta name="theme-color">` (one with a `media` attribute counts only
+  where its media matches), else the most common coloured background
+  of its buttons, else the colour of its links. Greys, muted colours, near black, near white and
+  the browser's own unstyled buttons do not count.
+- **corners:** the middle radius of the page's filled buttons, so the widget's buttons get the
+  same, up to 15px. A site where at least half of the filled buttons are pills keeps the
+  default.
+- **background and text**, with `theme: "auto"`: the page's background and text colour, and light
+  or dark from that background.
+
+A guess is used only when it contrasts: the accent 3:1 against the widget's background, the text
+4.5:1 against it. Otherwise the default stays: the system colours `Canvas`, `CanvasText` and
+`AccentColor`, light and dark from the system, and `16px` corners. With the page's text, the
+widget's hints take more of it than 60% where 60% would fall under 4.5:1. Each `--vf-*` variable
+the site sets wins over the guess for that variable; a site that sets only one of `--vf-surface`
+and `--vf-text` gets the other from the defaults.
 
 ## 2. CSS custom properties
 Set these on `visual-feedback` (or on any ancestor). Custom properties cross the shadow boundary.
@@ -15,19 +38,19 @@ Set these on `visual-feedback` (or on any ancestor). Custom properties cross the
 | variable | default | used for |
 |---|---|---|
 | `--vf-font` | `inherit` | font family of all text, such as `Inter, sans-serif` |
-| `--vf-radius` | `12px` | panel, inputs, buttons |
-| `--vf-surface` | `Canvas` | panel and toolbar background |
-| `--vf-text` | `CanvasText` | text |
-| `--vf-muted` | text at 60% | hints, counters |
+| `--vf-radius` | from the page's button corners, so the widget's buttons match them up to 15px (this is 1.6 times theirs, up to `24px`), else `16px` | panel and composer, and a share of it for buttons and the image |
+| `--vf-surface` | with `theme: "auto"` the page's background, else `Canvas` | panel, tool rail and composer background |
+| `--vf-text` | with `theme: "auto"` the page's text colour, else `CanvasText` | text |
+| `--vf-muted` | text at 60%, more on a page whose text would make that too faint | hints, counters |
 | `--vf-border` | text at 15% | hairlines |
-| `--vf-accent` | `AccentColor`, or `#0b57d0` where the browser has no `AccentColor` | Send button, active tool |
+| `--vf-accent` | the page's accent, else `AccentColor`, or `#0b57d0` where the browser has no `AccentColor` | Send button and its menu button, "Capture this view", active tool, chosen screenshot |
 | `--vf-accent-text` | black or white, whichever contrasts more with the accent | text on the accent |
 | `--vf-focus` | `--vf-accent` | focus ring |
 | `--vf-mark` | `#e5243b` | marks on the screenshot |
 | `--vf-backdrop` | `rgb(0 0 0 / 45%)` | overlay behind the image |
-| `--vf-shadow` | `0 4px 16px rgb(0 0 0 / 12%)` | trigger and panel |
-| `--vf-trigger-size` | `36px` | trigger diameter |
-| `--vf-offset` | `16px` | trigger distance from the edges |
+| `--vf-shadow` | `0 12px 32px -12px rgb(0 0 0 / 35%)` | trigger, panel and draft bar |
+| `--vf-trigger-size` | `2.5em`, 40px on a 16px site | trigger height, and its width when it shows the icon alone |
+| `--vf-offset` | `16px` | trigger and draft bar distance from the edges |
 | `--vf-z` | `2147483000` | stacking |
 
 ```css
@@ -39,9 +62,15 @@ visual-feedback {
 ```
 
 ## 3. `::part()`
-Every visible element has a part name: `trigger`, `trigger-icon`, `backdrop`, `dialog`, `title`,
-`image`, `toolbar`, `tool`, `tool-active`, `undo`, `clear`, `label`, `note`, `category`, `actions`, `cancel`, `send`,
-`status`, `error`, `retry`, `send-without`.
+Every visible element has a part name: `trigger`, `trigger-icon`, `trigger-text`, `backdrop`,
+`dialog`, `header`, `title`, `minimise`, `body`, `stage`, `image`, `toolbar`, `tool`, `tool-active`,
+`divider`, `undo`, `clear`, `remove`, `icon`, `text-input`, `selection`, `strip`, `thumb`,
+`thumb-pick`, `thumb-image`, `thumb-number`, `thumb-remove`, `add`, `label`, `composer`, `note`,
+`composer-bar`, `category`, `footer`, `split`, `send-more`, `menu`, `save-pdf`, `actions`, `cancel`,
+`send`, `hint`, `status`, `error`, `retry`, `send-without`, `draft`, `draft-label`, `draft-thumbs`,
+`capture-view`, `reopen`, `discard`, `confirm`, `confirm-text`, `keep-draft`, `keep-editing`. Cancel's
+question is `confirm`, also an `actions` part, with its own `discard` button. After a send error, the Send button's part is `retry` until it
+sends again, the same part as the capture error's "Try again".
 
 ```css
 visual-feedback::part(trigger) { opacity: .6; }
@@ -52,7 +81,8 @@ visual-feedback::part(trigger):hover { opacity: 1; }
 - `css` is a string. It is added as a constructable stylesheet inside the shadow root, after the
   defaults, so it can reach anything, including states that `::part()` cannot select.
 - `unstyled: true` drops every default except the layout-critical rules (the trigger's position and
-  size, the overlay's position, the panel's layout, canvas size, hidden states). Then the `css` option styles everything.
+  size, the overlay's position, the panel's layout, canvas size, hidden states) and the focus ring,
+  in `--vf-focus`, which `css` can restyle. Then the `css` option styles everything else.
 
 ```ts
 createFeedback({ onSubmit, css: `.toolbar { gap: 2px } .send { text-transform: uppercase }` });
@@ -61,5 +91,6 @@ Class names used inside the shadow root are part of the public API from 1.0. Bef
 change.
 
 ## Theme
-`theme: "light" | "dark"` sets `color-scheme` inside the shadow root, which forces that scheme.
-`"auto"` follows the system.
+`theme: "light" | "dark"` sets `color-scheme` inside the shadow root, which forces that scheme
+with the system colours. `"auto"` follows the page's background (section 1), and the system
+where the page shows none.