visual-feedback 0.0.0-stage → 0.2.0

package/docs/SPEC.md

@@ -0,0 +1,214 @@
+# visual-feedback: behaviour
+
+## 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 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  |   |                +--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, 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. 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. 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, 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), 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
+- **mode "dom"** (the default) serialises the DOM to an image, and needs no permission.
+- **mode "display"** uses `getDisplayMedia` for exact pixels, after the browser asks the user. The
+  image is what the user picks in the browser's prompt: this tab, another window or the whole
+  screen. If the user refuses, the browser does not support it, or the shared screen gives no
+  frame within 2 seconds, it falls back to "dom".
+- **Size:** in "dom", the image is the visible viewport at the device pixel ratio; in "display",
+  the shared surface. Both are scaled down to `maxWidth` (1920 by default).
+- **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 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 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).
+- 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. 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): 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
+  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
+The browsers that support constructable stylesheets (`adoptedStyleSheets`) and `color-mix()`:
+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
+  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
+  `img-src 'self' data:`. With same-origin styles and images, that is all it needs: it
+  works under `style-src 'self'`, with no `'unsafe-inline'`, in Chromium, Firefox and WebKit
+  (`tests/e2e/capture-csp.spec.ts`).
+- Cross-origin fonts, stylesheets and images are downloaded again with `fetch()`, which
+  `connect-src` governs. Where `connect-src` does not allow their origin, they are treated as §5
+  says for anything that cannot be drawn.
+
+## 12. Default copy
+These are the default texts. Each one can be replaced through `strings` (`docs/API.md`).
+
+| key | text |
+|---|---|
+| trigger | Send feedback |
+| title | Send feedback |
+| capturing | Taking a screenshot… |
+| captureError | Couldn't take a screenshot. |
+| sendWithout | Send without screenshot |
+| noteLabel | Your note |
+| notePlaceholder | What happened, or what would you change? |
+| noteRequired | Write a few words first. |
+| categoryLabel | Type |
+| 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

@@ -0,0 +1,72 @@
+# visual-feedback: theming
+
+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.
+
+## 2. CSS custom properties
+Set these on `visual-feedback` (or on any ancestor). Custom properties cross the shadow boundary.
+
+| variable | default | used for |
+|---|---|---|
+| `--vf-font` | `inherit` | font family of all text, such as `Inter, sans-serif` |
+| `--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 |
+| `--vf-accent` | `AccentColor`, or `#0b57d0` where the browser has no `AccentColor` | Send button, active tool |
+| `--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 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
+visual-feedback {
+  --vf-accent: #2563eb;
+  --vf-accent-text: #fff;
+  --vf-radius: 8px;
+}
+```
+
+## 3. `::part()`
+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; }
+visual-feedback::part(trigger):hover { opacity: 1; }
+```
+
+## 4. The `css` option and `unstyled`
+- `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) 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 }` });
+```
+Class names used inside the shadow root are part of the public API from 1.0. Before 1.0 they may
+change.
+
+## Theme
+`theme: "light" | "dark"` sets `color-scheme` inside the shadow root, which forces that scheme.
+`"auto"` follows the system.

package/docs/recipes/github-issues.md

@@ -0,0 +1,209 @@
+# Recipe: GitHub Issues (private repo only)
+
+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
+of who sent the report. The images show the screen as the user saw it, with nothing masked
+(SPEC §7). Only people with access to the repo see them. GitHub shows an image in an issue through
+a signed link that works for anyone who holds it, for a few minutes: show it, never share it.
+
+## 1. Pick a layout
+
+**A dedicated private repo (the default).** Create a private repo only for feedback, such as
+`<app>-feedback`, never the code repo, with a README so it has a default branch. Images stay out of the code repo's clones, and making the
+code repo public later exposes nothing. Images are committed to its default branch.
+
+**The code repo, with an orphan branch.** Only when you are sure the code repo stays private
+forever. Issues sit next to the code with one token, and images go to a branch `visual-feedback`
+that shares no history with the code. A token cannot be limited to one branch, so the server's
+token can also push to the code: a leak of it is a leak of write access to your source. But every clone and fetch downloads that branch unless it is
+cloned with `--single-branch`, and if the repo is ever made public, every report is exposed. Create
+the branch once, in a clean clone (git 2.23 or later):
+
+```sh
+git switch --orphan visual-feedback
+git commit --allow-empty -m "visual-feedback images"
+git push origin visual-feedback
+git switch -
+```
+
+In both layouts, deleting a file or a branch does not remove its images or reports: commits stay reachable by
+their SHA on GitHub until GitHub Support purges them. A later option, once it works with a
+fine-grained token, is GitHub's own issue-attachment upload, which keeps images out of git history;
+it is undocumented, so this recipe does not use it.
+
+## 2. Token and settings
+
+Create a fine-grained personal access token for that one repo, with **Issues: read and write** and
+**Contents: read and write**, and set on the server:
+
+| variable | for example |
+|---|---|
+| `GITHUB_FEEDBACK_REPO` | `acme/app-feedback` |
+| `GITHUB_FEEDBACK_TOKEN` | the token; never send it to the browser |
+| `GITHUB_FEEDBACK_BRANCH` | `visual-feedback` for the code-repo layout; unset for the default branch |
+
+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 `screenshot-<n>.webp` the same way, but whether
+the issue shows a WebP image inline is not checked.
+
+## 3. The route
+
+This is a Next.js App Router route on the Node.js runtime (it uses `Buffer`). As written, anyone who
+can reach `POST` can open issues, with any category as a label: before production, put it behind
+your own session check and a rate limit.
+
+```ts
+// app/api/feedback/route.ts
+import {
+  type FeedbackReport,
+  FeedbackRequestError,
+  parseFeedbackRequest,
+} from "visual-feedback/server";
+
+function github() {
+  const { GITHUB_FEEDBACK_REPO: repo, GITHUB_FEEDBACK_TOKEN: token } = process.env;
+  if (!repo || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !token) {
+    throw new Error("Set GITHUB_FEEDBACK_REPO (owner/name) and GITHUB_FEEDBACK_TOKEN.");
+  }
+  return async (method: string, path: string, body?: object, accept = "github+json") => {
+    const response = await fetch(`https://api.github.com/repos/${repo}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: `application/vnd.${accept}`,
+        "x-github-api-version": "2022-11-28",
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      cache: "no-store",
+    });
+    return { status: response.status, json: response.ok ? await response.json() : null };
+  };
+}
+
+// GitHub refuses an issue body over 65,536 characters; report.json keeps every field in full.
+function cut(text: string, max: number): string {
+  const chars = Array.from(text);
+  return chars.length > max ? `${chars.slice(0, max).join("")}…` : text;
+}
+
+// A fence longer than any run of backticks in the text, so the text shows as written.
+function fenced(text: string, max: number): string {
+  const shown = cut(text, max);
+  const longest = Math.max(2, ...[...shown.matchAll(/`+/g)].map((run) => run[0].length));
+  const fence = "`".repeat(longest + 1);
+  return `${fence}text\n${shown}\n${fence}`;
+}
+
+// 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 * share),
+    // The angle brackets keep a ( or ) in a branch name from ending the link.
+    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 * share)}`,
+  ].join("\n\n");
+}
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    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.
+    if (repo.status !== 200) throw new Error(`GitHub answered ${repo.status} for the repo.`);
+    if (repo.json.private !== true) {
+      return new Response("The feedback repo must be private.", { status: 503 });
+    }
+    const branch = process.env.GITHUB_FEEDBACK_BRANCH || repo.json.default_branch;
+    const ref = `?ref=${encodeURIComponent(branch)}`;
+    const folder = `feedback/${report.id}`;
+    // The plain JSON answer refuses a file over 1 MB; the object one only leaves out its content.
+    const stored = (name: string) =>
+      api("GET", `/contents/${folder}/${name}${ref}`, undefined, "github.object");
+    // report.json is written last, so its presence means the issue exists: a resend stops here.
+    const marker = await stored("report.json");
+    if (marker.status === 200) return new Response(null, { status: 204 });
+    if (marker.status !== 404) throw new Error(`GitHub answered ${marker.status} for report.json.`);
+    const put = async (name: string, bytes: Uint8Array) => {
+      const content = Buffer.from(bytes).toString("base64");
+      const message = `Feedback ${report.id}: ${name}`;
+      // No sha, so GitHub only creates: an existing file is never replaced (422).
+      let commit = await api("PUT", `/contents/${folder}/${name}`, { message, content, branch });
+      // Two commits to one branch at once: GitHub refuses the second with 409.
+      for (let retry = 0; commit.status === 409 && retry < 2; retry++) {
+        commit = await api("PUT", `/contents/${folder}/${name}`, { message, content, branch });
+      }
+      if (commit.status === 201) return;
+      // GitHub also answers 422 for a missing branch, so only a file already there counts.
+      if (commit.status !== 422 || (await stored(name)).status !== 200) {
+        throw new Error(`GitHub answered ${commit.status} for ${name}.`);
+      }
+    };
+    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}`;
+      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, imageUrls),
+      labels: ["feedback", ...(category ? [category] : [])],
+    });
+    if (issue.status !== 201) throw new Error(`GitHub answered ${issue.status} for the issue.`);
+    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) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+```
+
+If the issue opens but `report.json` cannot be written, a "Try again" opens a second issue for the
+same report. Two sends of one report at the same moment can also both open one, since the check
+and the writes are separate. Each issue body names the report id, so the two are easy to match.

package/docs/recipes/local.md

@@ -0,0 +1,75 @@
+# Recipe: a local `.visual-feedback/` folder
+
+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 `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.
+
+The images show the screen as the user saw it, with nothing masked (SPEC §7), so treat the folder
+as private.
+
+## 1. Keep the folder out of git
+
+Add this line to `.gitignore`:
+
+```gitignore
+.visual-feedback/
+```
+
+## 2. The route
+
+The widget posts to it with `createFeedback({ endpoint: "/api/feedback" })`. This is a Next.js
+App Router route. Other servers that hand you a Web `Request` on Node can call the same function;
+one that hands you Node's `IncomingMessage`, such as Express, needs an adapter first. The route
+checks no user, so keep the dev server on localhost: `next dev` listens on every network
+interface unless it is started as `next dev -H 127.0.0.1`.
+
+```ts
+// app/api/feedback/route.ts
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
+
+export async function POST(request: Request): Promise<Response> {
+  // Development only: a deployed disk can be read-only or wiped, and NODE_ENV may be unset.
+  if (process.env.NODE_ENV !== "development") {
+    return new Response("Local feedback storage works only in development.", { status: 503 });
+  }
+  try {
+    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 name = (image: Blob, i: number) =>
+      `screenshot-${i}.${image.type === "image/png" ? "png" : "webp"}`;
+    await mkdir(folder, { recursive: true });
+    // 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, screenshots }, null, 2),
+    );
+    // 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) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+```
+
+A "Try again" sends the same report again, with the same `id`, so it writes over its own folder and
+never makes a second one.