visual-feedback 0.0.0-stage → 0.1.0

package/docs/API.md

@@ -0,0 +1,119 @@
+# visual-feedback: API
+
+ESM only, with TypeScript types. On first open it imports `@zumer/snapdom` by name, so a page
+needs a bundler, or an import map that points that name to the file. There are three entry points:
+
+| import | for | runs in |
+|---|---|---|
+| `visual-feedback` | `createFeedback()` 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
+
+```ts
+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 res = await fetch("/api/feedback", { method: "POST", body });
+    if (!res.ok) throw new Error("It didn't send. Your note is kept.");
+  },
+});
+```
+
+### Options
+| option | type | default | meaning |
+|---|---|---|---|
+| `onSubmit` | `(report) => Promise<void>` | – | Sends the report. A throw shows the send error state, using the error's message. Give this or `endpoint`; with both, `onSubmit` is used. |
+| `endpoint` | `string` | – | POSTs `multipart/form-data` with a `report` part (JSON, 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()`. |
+| `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. |
+| `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`. |
+| `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. |
+| `container` | `HTMLElement` | `document.body` | Where the host element is appended. |
+| `tagName` | `string` | `"visual-feedback"` | The custom element name, if it clashes. |
+
+### 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. |
+
+## FeedbackReport
+```ts
+type FeedbackReport = {
+  id: string;                       // UUID v4 from crypto.getRandomValues, so plain http works
+  createdAt: string;                // ISO 8601
+  note: string;
+  category?: string;
+  image: Blob | null;               // marks painted in; null after "Send without screenshot"
+  marks: Mark[];                    // vectors, in image pixels
+  page: { url: string; title: string };
+  viewport: { width: number; height: number; devicePixelRatio: number };
+  scroll: { x: number; y: number };
+  userAgent: string;
+  language: string;
+  timeZone: string;
+  context: Record<string, unknown>;
+};
+type Mark =
+  | { tool: "pen"; points: [number, number][] }
+  | { tool: "box"; x: number; y: number; width: number; height: number }
+  | { tool: "arrow"; from: [number, number]; to: [number, number] };
+```
+
+## `<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
+client component, so a server component can render it with props that reach the browser as data,
+such as `endpoint`; `onSubmit`, `headers` as a function, `context` and `container` need a client
+component.
+
+```tsx
+import { Feedback } from "visual-feedback/react";
+
+<Feedback endpoint="/api/feedback" />;
+```
+
+## parseFeedbackRequest(request, limits?) (`visual-feedback/server`)
+```ts
+const { report, image } = 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`
+  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
+  `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).
+- 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

@@ -0,0 +1,128 @@
+# 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 stores nothing and sends nothing by itself.
+
+## 2. Flow
+```
+idle --open--> capturing --image ready--> annotating --Send--> sending --ok--> sent --3 s--> idle
+                   |                          |                    |
+                   +--fails--> capture error  +--Cancel/Esc--> idle +--fails--> send error
+```
+- **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.
+- **sending:** the note, the category and the tools are disabled, and the Send button shows
+  progress. Cancel and Esc still 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.
+
+## 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 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`.
+
+## 4. Annotating
+- **Tools:** Pen (freehand), Box (rectangle outline) and Arrow. Undo removes the last mark, 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`).
+- 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.
+
+## 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 note and the category;
+- the page URL and title, the viewport and the scroll position, as they were at the 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.
+- 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`).
+- 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
+  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.
+- 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
+  no inline `style` attributes, 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 | Draw / Box / Arrow |
+| 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 |

package/docs/THEMING.md

@@ -0,0 +1,65 @@
+# 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` | `12px` | panel, inputs, buttons |
+| `--vf-surface` | `Canvas` | panel and toolbar 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 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-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`, `backdrop`, `dialog`, `title`,
+`image`, `toolbar`, `tool`, `tool-active`, `undo`, `clear`, `label`, `note`, `category`, `actions`, `cancel`, `send`,
+`status`, `error`, `retry`, `send-without`.
+
+```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). Then the `css` option styles everything.
+
+```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,185 @@
+# 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
+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 `image.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}`;
+}
+
+function issueBody(report: FeedbackReport, imageUrl: string | null): 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),
+    // 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)}`,
+    `**Sent:** ${createdAt}, report \`${id}\``,
+    `**Context, from the browser:**\n${fenced(JSON.stringify(report.context, null, 2), 6_000)}`,
+  ].join("\n\n");
+}
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const { report, image } = 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}.`);
+      }
+    };
+    let imageUrl: string | null = null;
+    if (image) {
+      const name = `image.${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`;
+    }
+    // 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),
+      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);
+    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,71 @@
+# 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 `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.
+
+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, 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, image } = 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;
+    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()));
+    await writeFile(
+      join(folder, "report.json"),
+      JSON.stringify({ ...report, image: file }, 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 });
+    }
+    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.

package/docs/recipes/postgres.md

@@ -0,0 +1,92 @@
+# 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).
+
+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`.
+5. Read images back with that recipe's `GET`, its `canRead` replaced by the same admin check your
+   screens use.
+
+The images show the screen as the user saw it, with nothing masked (SPEC §7), so read the table only
+from your own admin screens.
+
+## 1. Install and create the table
+
+```sh
+npm install postgres
+```
+
+```sql
+create table feedback_reports (
+  id uuid primary key,
+  user_id text not null,
+  created_at timestamptz not null,
+  report jsonb not null,
+  image bytea,
+  image_type text
+);
+```
+
+Set `DATABASE_URL` on the server. On a serverless host, use your provider's pooled URL, since each
+instance opens its own connections; a pooler in transaction mode also needs `prepare: false` beside
+`idle_timeout` below.
+
+## 2. The route
+
+The widget posts to it with `createFeedback({ endpoint: "/api/feedback" })`. This is a Next.js
+App Router route.
+
+```ts
+// app/api/feedback/route.ts
+import postgres from "postgres";
+import { FeedbackRequestError, parseFeedbackRequest } from "visual-feedback/server";
+
+let sql: postgres.Sql | undefined;
+
+// Connects on the first send, so a build or an import never opens a connection.
+function db(): postgres.Sql {
+  if (!process.env.DATABASE_URL) throw new Error("Set DATABASE_URL.");
+  // idle_timeout closes a pool a hot reload left behind, instead of holding its connections.
+  sql ??= postgres(process.env.DATABASE_URL, { idle_timeout: 20 });
+  return sql;
+}
+
+// Replace with your own session: the user who is signed in. Until then, nobody can send.
+// Never take the user from report.context, which the browser controls.
+async function currentUser(_request: Request): Promise<string | null> {
+  return null;
+}
+
+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;
+    // 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`;
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof FeedbackRequestError) {
+      return new Response(error.message, { status: error.status });
+    }
+    throw error;
+  }
+}
+```