visual-feedback 0.1.0 → 0.2.0

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 is hidden while there is a draft, whether the dialog is open or kept in the draft bar.
 - It does not watch the page. 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,67 @@ 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"`).
 
 ## 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 at load; 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 +166,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`) 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 +193,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

@@ -15,8 +15,8 @@ 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-radius` | `16px` | panel and composer, and a share of it for buttons and the image |
+| `--vf-surface` | `Canvas` | panel, tool rail and composer background |
 | `--vf-text` | `CanvasText` | text |
 | `--vf-muted` | text at 60% | hints, counters |
 | `--vf-border` | text at 15% | hairlines |
@@ -25,9 +25,9 @@ Set these on `visual-feedback` (or on any ancestor). Custom properties cross the
 | `--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 +39,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 +58,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 }` });

package/docs/recipes/github-issues.md

@@ -1,10 +1,12 @@
 # Recipe: GitHub Issues (private repo only)
 
-Each report becomes an issue: the note, the page URL, the browser data and the image, with the
-category as a label. The image is committed to the repo with GitHub's contents API, at
-`feedback/<id>/image.png`, and shown inside the issue. Then the whole report is committed beside
-it as `feedback/<id>/report.json`, with `image` set to the image's GitHub link (or `null`) and
-`issue` to the issue number: a resend that finds it opens no second issue. The route checks on every send that the repo
+Each report becomes an issue: the note, the page URL, the browser data and the screenshots, with
+the category as a label. Each screenshot's image is committed to the repo with GitHub's contents
+API, at `feedback/<id>/screenshot-<n>.png`, numbered from 0, and shown inside the issue, with its
+own page URL under it when it was taken on another page than the report's. Then the
+whole report is committed beside them as `feedback/<id>/report.json`, with each screenshot's `image`
+set to its GitHub link and `issue` to the issue number: a resend that finds it opens no second
+issue. The route checks on every send that the repo
 is private, and refuses otherwise. It uses `fetch` and GitHub's REST API, so it needs no package.
 
 `report.context` comes from the browser (docs/API.md): the issue shows it as data, never as proof
@@ -50,7 +52,7 @@ Create a fine-grained personal access token for that one repo, with **Issues: re
 
 Send PNG from the widget, the image type this recipe was checked with inside an issue:
 `createFeedback({ endpoint: "/api/feedback", capture: { type: "image/png" } })`. Without it the
-widget sends WebP (docs/API.md): the route commits and links `image.webp` the same way, but whether
+widget sends WebP (docs/API.md): the route commits and links `screenshot-<n>.webp` the same way, but whether
 the issue shows a WebP image inline is not checked.
 
 ## 3. The route
@@ -101,24 +103,46 @@ function fenced(text: string, max: number): string {
   return `${fence}text\n${shown}\n${fence}`;
 }
 
-function issueBody(report: FeedbackReport, imageUrl: string | null): string {
+// A screenshot of another page than the report's names its own, as a draft can span routes.
+function shots(report: FeedbackReport, imageUrls: string[], share: number): string {
+  return imageUrls
+    .map((url, i) => {
+      const page = report.screenshots[i]?.page.url ?? report.page.url;
+      const where = page === report.page.url ? "" : `\n${fenced(page, 2_000 * share)}`;
+      return `![Screenshot ${i + 1}](<${url}>)${where}`;
+    })
+    .join("\n\n");
+}
+
+function issueBody(report: FeedbackReport, imageUrls: string[]): string {
+  // A fence can be as long as its text, so a report of backticks can pass GitHub's limit at the
+  // usual cuts: they shrink until it fits. At a tenth, the longest report is far under it.
+  let body = "";
+  for (const share of [1, 0.5, 0.25, 0.1]) {
+    body = bodyAt(report, imageUrls, share);
+    if (body.length <= 65_536) break;
+  }
+  return body;
+}
+
+function bodyAt(report: FeedbackReport, imageUrls: string[], share: number): string {
   const { page, viewport, userAgent, language, timeZone, createdAt, id } = report;
   const screen = `${viewport.width}x${viewport.height} @${viewport.devicePixelRatio}x`;
   // Each fence starts its own line: after other text on that line it is no block.
   return [
-    fenced(report.note || "(no note)", 10_000),
+    fenced(report.note || "(no note)", 10_000 * share),
     // The angle brackets keep a ( or ) in a branch name from ending the link.
-    imageUrl ? `![Screenshot](<${imageUrl}>)` : "No screenshot.",
-    `**Page:**\n${fenced(page.url, 2_000)}`,
-    `**Browser:**\n${fenced(`${userAgent}\n${screen}, ${language}, ${timeZone}`, 1_000)}`,
+    shots(report, imageUrls, share) || "No screenshot.",
+    `**Page:**\n${fenced(page.url, 2_000 * share)}`,
+    `**Browser:**\n${fenced(`${userAgent}\n${screen}, ${language}, ${timeZone}`, 1_000 * share)}`,
     `**Sent:** ${createdAt}, report \`${id}\``,
-    `**Context, from the browser:**\n${fenced(JSON.stringify(report.context, null, 2), 6_000)}`,
+    `**Context, from the browser:**\n${fenced(JSON.stringify(report.context, null, 2), 6_000 * share)}`,
   ].join("\n\n");
 }
 
 export async function POST(request: Request): Promise<Response> {
   try {
-    const { report, image } = await parseFeedbackRequest(request);
+    const { report } = await parseFeedbackRequest(request);
     const api = github();
     const repo = await api("GET", "");
     // Checked on every send: a repo made public later must not receive reports.
@@ -151,24 +175,24 @@ export async function POST(request: Request): Promise<Response> {
         throw new Error(`GitHub answered ${commit.status} for ${name}.`);
       }
     };
-    let imageUrl: string | null = null;
-    if (image) {
-      const name = `image.${image.type === "image/png" ? "png" : "webp"}`;
+    const imageUrls: string[] = [];
+    for (const [i, { image }] of report.screenshots.entries()) {
+      const name = `screenshot-${i}.${image.type === "image/png" ? "png" : "webp"}`;
       await put(name, new Uint8Array(await image.arrayBuffer()));
       const path = `${branch.split("/").map(encodeURIComponent).join("/")}/${folder}/${name}`;
-      imageUrl = `https://github.com/${repo.json.full_name}/blob/${path}?raw=true`;
+      imageUrls.push(`https://github.com/${repo.json.full_name}/blob/${path}?raw=true`);
     }
     // GitHub refuses a label name over 50 characters, and one that is only space.
     const category = cut(report.category?.replace(/\s+/g, " ").trim() ?? "", 49);
     const title = cut(report.note.split("\n")[0]?.trim() || "Feedback", 80);
     const issue = await api("POST", "/issues", {
       title,
-      body: issueBody(report, imageUrl),
+      body: issueBody(report, imageUrls),
       labels: ["feedback", ...(category ? [category] : [])],
     });
     if (issue.status !== 201) throw new Error(`GitHub answered ${issue.status} for the issue.`);
-    const { image: _, ...rest } = report;
-    const json = JSON.stringify({ ...rest, image: imageUrl, issue: issue.json.number }, null, 2);
+    const screenshots = report.screenshots.map((shot, i) => ({ ...shot, image: imageUrls[i] }));
+    const json = JSON.stringify({ ...report, screenshots, issue: issue.json.number }, null, 2);
     await put("report.json", new TextEncoder().encode(json));
     return new Response(null, { status: 204 });
   } catch (error) {

package/docs/recipes/local.md

@@ -3,9 +3,9 @@
 For local development only: it writes only when `NODE_ENV` is `development`. `next dev` sets it;
 start any other server with `NODE_ENV=development`.
 
-Each report becomes one folder, `.visual-feedback/<id>/`, holding `image.png` or `image.webp` and
-`report.json`. That file is the `FeedbackReport` (docs/API.md), with `image` set to the image's file
-name, or `null` when the report has none.
+Each report becomes one folder, `.visual-feedback/<id>/`, holding `report.json` and one image per
+screenshot: `screenshot-0.png` or `screenshot-0.webp`, then `screenshot-1`, and so on. That file is
+the `FeedbackReport` (docs/API.md), with each screenshot's `image` set to its file name.
 
 It does not work on hosts whose disk is read-only or wiped on each deploy or restart, such as
 Vercel, Netlify, Cloudflare and most containers. Use another recipe there.
@@ -31,7 +31,7 @@ interface unless it is started as `next dev -H 127.0.0.1`.
 
 ```ts
 // app/api/feedback/route.ts
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
 
@@ -41,21 +41,25 @@ export async function POST(request: Request): Promise<Response> {
     return new Response("Local feedback storage works only in development.", { status: 503 });
   }
   try {
-    const { report, image } = await parseFeedbackRequest(request);
+    const { report } = await parseFeedbackRequest(request);
     // report.id is a checked UUID, so it is safe as a folder name.
     const folder = join(process.cwd(), ".visual-feedback", report.id);
-    const file = image ? `image.${image.type === "image/png" ? "png" : "webp"}` : null;
+    const name = (image: Blob, i: number) =>
+      `screenshot-${i}.${image.type === "image/png" ? "png" : "webp"}`;
     await mkdir(folder, { recursive: true });
-    // The image first: a report.json on disk then always has its image beside it.
-    if (image && file)
-      await writeFile(join(folder, file), new Uint8Array(await image.arrayBuffer()));
+    // The images first: a report.json on disk then always has its images beside it.
+    for (const [i, { image }] of report.screenshots.entries()) {
+      await writeFile(join(folder, name(image, i)), new Uint8Array(await image.arrayBuffer()));
+    }
+    const screenshots = report.screenshots.map((shot, i) => ({ ...shot, image: name(shot.image, i) }));
     await writeFile(
       join(folder, "report.json"),
-      JSON.stringify({ ...report, image: file }, null, 2),
+      JSON.stringify({ ...report, screenshots }, null, 2),
     );
-    // After report.json, so a resend with another image type, or none, leaves no stray image.
-    for (const old of ["image.png", "image.webp"]) {
-      if (old !== file) await rm(join(folder, old), { force: true });
+    // After report.json, so a resend with other images, or fewer, leaves no stray image.
+    const kept = new Set(["report.json", ...screenshots.map((shot) => shot.image)]);
+    for (const old of await readdir(folder)) {
+      if (!kept.has(old)) await rm(join(folder, old), { force: true });
     }
     return new Response(null, { status: 204 });
   } catch (error) {

package/docs/recipes/postgres.md

@@ -1,18 +1,21 @@
 # Recipe: Postgres
 
-Each report becomes one row: the `FeedbackReport` (docs/API.md) without its `image` as `jsonb`, the
-image in `image` (`bytea`) with its type in `image_type`, and the user who sent it, taken from your
-own session. `user_id` is the proof of who sent a report; `report.context` is not (docs/API.md).
+Each report becomes one row in `feedback_reports`: the `FeedbackReport` (docs/API.md), its
+screenshots without their images, as `jsonb`, and the user who sent it, taken from your own session.
+Each screenshot's image becomes one row in `feedback_screenshots`, by its `position` in
+`report.screenshots`: the image in `image` (`bytea`) and its type in `image_type`. `user_id` is the
+proof of who sent a report; `report.context` is not (docs/API.md).
 
 To keep images in a bucket instead (docs/recipes/s3.md):
 
 1. Install `aws4fetch` and set the `S3_*` variables as that recipe's step 1 says.
 2. Copy its `bucket()` function into this route.
-3. Before the insert, PUT the image to `url(report.id, "image.png")` or `"image.webp"`, as that
-   recipe's `POST` does: with `"if-none-match": "*"`, so a reused id never replaces a stored
-   image, and throw on any refusal but 412, so a row never lacks its image.
-4. Insert `null` for `image` and keep `image_type`: `image/png` is the file `image.png`, and
-   `image/webp` is `image.webp`.
+3. Before the insert, PUT each image to `url(report.id, "screenshot-<position>.png")` or `.webp`,
+   as that recipe's `POST` does:
+   with `"if-none-match": "*"`, so a reused id never replaces a stored image, and throw on any
+   refusal but 412, so a row never lacks its image.
+4. Insert `null` for `image` and keep `image_type`: `image/png` is the file
+   `screenshot-<position>.png`, and `image/webp` is `screenshot-<position>.webp`.
 5. Read images back with that recipe's `GET`, its `canRead` replaced by the same admin check your
    screens use.
 
@@ -30,9 +33,15 @@ create table feedback_reports (
   id uuid primary key,
   user_id text not null,
   created_at timestamptz not null,
-  report jsonb not null,
+  report jsonb not null
+);
+
+create table feedback_screenshots (
+  report_id uuid not null references feedback_reports (id) on delete cascade,
+  position integer not null,
   image bytea,
-  image_type text
+  image_type text not null,
+  primary key (report_id, position)
 );
 ```
 
@@ -70,17 +79,30 @@ export async function POST(request: Request): Promise<Response> {
   const user = await currentUser(request);
   if (!user) return new Response(null, { status: 401 });
   try {
-    const { report, image } = await parseFeedbackRequest(request);
-    const { image: _, ...stored } = report;
-    const bytes = image ? new Uint8Array(await image.arrayBuffer()) : null;
+    const { report } = await parseFeedbackRequest(request);
+    const screenshots = report.screenshots.map(({ image: _, ...shot }) => shot);
     // The report was parsed from JSON, so it is JSON; context is only typed as unknown values.
-    const json = db().json(stored as postgres.JSONValue);
-    // A "Try again" sends the same id, so the row it already wrote stays as it is.
-    await db()`
-      insert into feedback_reports (id, user_id, created_at, report, image, image_type)
-      values (${report.id}, ${user}, ${report.createdAt}, ${json}, ${bytes},
-        ${image?.type ?? null})
-      on conflict (id) do nothing`;
+    const json = db().json({ ...report, screenshots } as postgres.JSONValue);
+    const images = await Promise.all(
+      report.screenshots.map(async ({ image }, position) => ({
+        report_id: report.id,
+        position,
+        image: new Uint8Array(await image.arrayBuffer()),
+        image_type: image.type,
+      })),
+    );
+    // One transaction, so a report row never lacks its screenshots.
+    await db().begin(async (sql) => {
+      // A "Try again" sends the same id, so the rows it already wrote stay as they are.
+      const inserted = await sql`
+        insert into feedback_reports (id, user_id, created_at, report)
+        values (${report.id}, ${user}, ${report.createdAt}, ${json})
+        on conflict (id) do nothing
+        returning id`;
+      if (inserted.length && images.length) {
+        await sql`insert into feedback_screenshots ${sql(images)}`;
+      }
+    });
     return new Response(null, { status: 204 });
   } catch (error) {
     if (error instanceof FeedbackRequestError) {

package/docs/recipes/s3.md

@@ -1,8 +1,8 @@
 # Recipe: an S3-compatible bucket (S3, R2, Railway Buckets)
 
-Each report becomes two objects in a private bucket, named and shaped as in the local recipe
-(docs/recipes/local.md): `feedback/<id>/report.json`, whose `image` is the image's name, and
-`feedback/<id>/image.png` or `image.webp`.
+Each report becomes objects in a private bucket, its report and one per screenshot, named and shaped as in the local recipe
+(docs/recipes/local.md): `feedback/<id>/report.json`, where each screenshot's `image` is its file
+name, and `feedback/<id>/screenshot-<n>.png` or `.webp` for each screenshot, numbered from 0.
 
 The bucket stays private: nothing is public, and people read reports only through your own route,
 behind your own admin check. `report.context` comes from the browser (docs/API.md), so an admin view
@@ -64,7 +64,7 @@ function bucket() {
 
 export async function POST(request: Request): Promise<Response> {
   try {
-    const { report, image } = await parseFeedbackRequest(request);
+    const { report } = await parseFeedbackRequest(request);
     const { client, url } = bucket();
     // A report already stored under this id stays: a retry, or a reused id, changes nothing.
     const stored = await client.fetch(url(report.id, "report.json"), { method: "HEAD" });
@@ -73,11 +73,15 @@ export async function POST(request: Request): Promise<Response> {
     if (stored.status !== 403 && stored.status !== 404) {
       throw new Error(`The bucket answered ${stored.status} for report.json.`);
     }
-    const name = image ? `image.${image.type === "image/png" ? "png" : "webp"}` : null;
-    // The image first: a report.json in the bucket then always has its image beside it.
+    const name = (image: Blob, i: number) =>
+      `screenshot-${i}.${image.type === "image/png" ? "png" : "webp"}`;
+    const screenshots = report.screenshots.map((shot, i) => ({ ...shot, image: name(shot.image, i) }));
+    // The images first: a report.json in the bucket then always has its images beside it.
     const puts: [string, BodyInit, string][] = [
-      ...(image && name ? [[name, image, image.type] as [string, BodyInit, string]] : []),
-      ["report.json", JSON.stringify({ ...report, image: name }), "application/json"],
+      ...report.screenshots.map(
+        ({ image }, i): [string, BodyInit, string] => [name(image, i), image, image.type],
+      ),
+      ["report.json", JSON.stringify({ ...report, screenshots }), "application/json"],
     ];
     for (const [file, body, type] of puts) {
       const put = await client.fetch(url(report.id, file), {
@@ -99,14 +103,15 @@ export async function POST(request: Request): Promise<Response> {
   }
 }
 
-// GET /api/feedback?id=<report id>&file=report.json | image.png | image.webp
+// GET /api/feedback?id=<report id>&file=report.json | screenshot-<n>.png | screenshot-<n>.webp
 export async function GET(request: Request): Promise<Response> {
   if (!(await canRead(request))) return new Response(null, { status: 403 });
   const query = new URL(request.url).searchParams;
   const id = query.get("id") ?? "";
   const file = query.get("file") ?? "";
   // Only a report id and a known file name, so the key cannot leave feedback/<id>/.
-  if (!/^[0-9a-f-]{36}$/.test(id) || !["report.json", "image.png", "image.webp"].includes(file)) {
+  const known = file === "report.json" || /^screenshot-\d\.(png|webp)$/.test(file);
+  if (!/^[0-9a-f-]{36}$/.test(id) || !known) {
     return new Response(null, { status: 400 });
   }
   const { client, url } = bucket();