@getpinax/widget 0.0.0-stage → 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,514 @@
-# Temporary Holding Version
+# Pinax widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The script customers embed (requirements sections 1 and 2): a feedback button,
+a panel with three kinds of feedback, screenshots with markup, and automatic
+page context.
+
+## Install
+
+### npm (S-10)
+
+```bash
+npm install @getpinax/widget
+```
+
+```ts
+import { init, open, identify, consent, destroy } from '@getpinax/widget';
+
+// Once, as early as you like (e.g. in your app's entry file). Browser only.
+init({ key: 'pk_...' });
+
+// From your cookie banner, on sites that wait for consent (see Visitor consent).
+consent({ diagnostics: true, replay: true });
+
+// When someone signs in, so their reports carry who they are (C-09).
+identify({ id: user.id, name: user.name, email: user.email });
+identify(null); // on sign-out
+
+// From your own "Give feedback" link or button (S-05).
+document.querySelector('#feedback')?.addEventListener('click', () => open());
+
+// On teardown (tests, micro-frontends). Restores console, fetch and XHR.
+destroy();
+```
+
+React example:
+
+```tsx
+import { useEffect } from 'react';
+import { init, identify } from '@getpinax/widget';
+
+export function Feedback({ user }: { user?: { id: string; email: string } }) {
+  useEffect(() => init({ key: 'pk_...' }), []);
+  useEffect(() => identify(user ?? null), [user]);
+  return null;
+}
+```
+
+The package is an ES module with TypeScript types. It does nothing on import;
+`init()` starts it. The screenshot editor and the session recorder are
+dynamic `import()` chunks, so your bundler splits them out and they load only
+when needed. On server-rendered frameworks, call `init()` in the browser only
+(`useEffect`, `onMount`, a client component).
+
+Options: `key` (the website key from Install), `apiUrl` (default
+`https://api.getpinax.com`), `cdnUrl` (default `https://cdn.getpinax.com`,
+where the site's settings are read from, P-15) and `consent` (`'wait'` or
+`'none'`, overriding the site's "Wait for visitor consent" setting; see
+Visitor consent). With only `apiUrl` set, settings come from that API, which
+is what you want for a local backend.
+
+### Script tag (CDN)
+
+```html
+<script src="https://cdn.getpinax.com/pinax.js" data-key="pk_..." async></script>
+<!-- data-api="https://api.example" overrides the API origin, data-cdn="https://cdn.example" the settings origin,
+     data-consent="wait" or "none" the site's "Wait for visitor consent" setting -->
+```
+
+### Publishing
+
+Releases go to npm and cdn.getpinax.com together, from a clean `main`:
+
+```bash
+yarn release                 # next beta: 1.0.0-beta.1 → 1.0.0-beta.2 (npm tag "beta")
+yarn release 1.0.0           # a stable version (npm tag "latest"); also patch|minor|major
+yarn release --dry-run       # check, test and pack; changes nothing
+yarn release --cdn-only      # npm worked but the CDN upload failed: upload again
+```
+
+`scripts/release.sh` checks you're on `main`, clean and in step with
+`origin`, runs lint and tests, bumps `version`, commits and tags `v<version>`,
+then publishes to npm. `prepublishOnly` builds with
+`VITE_PINAX_API=https://api.getpinax.com` and `VITE_PINAX_CDN=https://cdn.getpinax.com`
+and tests again. Next it uploads the build with `cdn/deploy.sh` (the Worker is
+redeployed only when `cdn/` changed, or with `--worker`), pushes the commit and
+tag, and checks npm and the CDN serve the new version. If npm refuses (no 2FA
+code, version taken), the local commit and tag are undone.
+
+It needs `npm login` (with 2FA; pass `--otp <code>` or confirm in the browser)
+and the Cloudflare deploy credentials `CLOUDFLARE_API_TOKEN`,
+`CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_ZONE_ID`, exported or in
+`~/.config/pinax/cdn.env` (outside the repo). `version` is also the `?v=` the
+script tag uses to load matching editor and recorder files, and
+`/v/<version>/` files are cached for a year, so a version is never reused.
+
+## API
+
+| Call | What it does |
+|---|---|
+| `init({ key, apiUrl?, cdnUrl?, segment?, consent? })` | Starts capture and fetches settings (from the CDN, P-15). Later calls are ignored. The script tag calls it after the page's `load` event. |
+| `open()` | Opens the panel from the site's own link (S-05). Before settings arrive, it opens once they do. Works with `hideButton` and on hidden paths. Closing returns focus to whatever had it before. |
+| `identify({ id?, name?, email? } \| null)` | Attaches the signed-in visitor's id and name to reports (C-09). Works before `init`. The email only fills in the form's email box (unless the site's `identifyPrefill` is off) and is sent only if the visitor leaves it there; it's never sent on its own. |
+| `setBasket({ value, currency } \| null)` | What's in the shopper's basket now, in major units (`42.5`, not `4250`) and an ISO code (`'GBP'`); `null` once it's empty. Works before `init`. Sent only with a sampled sighting of a known error (AI-21), never on its own. |
+| `consent(true \| false \| { diagnostics?, replay? })` | The visitor's answer to the site's cookie banner (see Visitor consent). `true`/`false` set both parts; the object form changes only the parts given. Works before `init`, and as often as the banner reports a change; withdrawing stops what it covers at once. Only matters where the page waits for consent. |
+| `destroy()` | Removes the widget and restores `console`, `fetch` and `XMLHttpRequest`. |
+
+With the script tag these are on `window.Pinax`.
+
+```ts
+// A shop: keep the basket up to date.
+setBasket({ value: cart.total, currency: 'GBP' });
+setBasket(null); // emptied
+```
+
+## Settings
+
+The widget follows the settings from `GET /v1/widget/{key}/config`
+(`backend/src/modules/widget/widget-settings.ts`). Anything missing or
+malformed falls back to the defaults (`src/settings.ts`).
+
+| Setting | Effect |
+|---|---|
+| `color`, `text`, `position` | Button colour, label and placement (S-01). |
+| `types`, `rating` | Which feedback types are offered; stars on General (S-02). |
+| `hidePaths` | No button on matching paths (S-04). Matched against `location.pathname`; `*` matches anything, so `/checkout/*` covers `/checkout`, `/checkout/` and `/checkout/pay/2`. `/pricing` covers `/pricing` and `/pricing/` only. Case-sensitive. Re-checked on `popstate`, `history.pushState` and `history.replaceState`, so single-page sites work. An open panel stays open when the visitor navigates to a hidden path. |
+| `smallOnMobile` | A smaller button on screens up to 520 px wide (S-04). |
+| `segment` | Off by default. When on and the page runs Segment, the widget sends its events to `window.analytics` (see Segment below). |
+| `hideButton` | No floating button at all; the site calls `Pinax.open()` (S-05). The panel then sits 24 px from the bottom instead of above the button. |
+| `knownIssues` | `{ enabled, notify }`, both on by default. `enabled` shows the "We know about this" card (see Known issues below); `notify` offers "Email me when it's fixed" after Me too. |
+| `consent` | `{ required }`, off by default. On: the site shows a cookie banner, so replay, technical logs, error counts and the page-view count wait for `Pinax.consent()` (see Visitor consent). `data-consent` / the `consent` option overrides it. |
+| `identifyPrefill` | On by default. The email given to `identify()` fills in the form's email box; the visitor can change or clear it, and a box they cleared isn't filled in again on this page. Off: the box starts empty. Either way only what's in the box is sent (`email`); `user` carries the id and name only. |
+| `privacyUrl` | The site's privacy policy (an `https:` address on one of its domains; the dashboard checks that). When set, the form's notice links it ("Privacy policy", new tab). Anything that isn't `https:` is ignored. |
+| `wording` | S-06. An empty string keeps the default. `chooserTitle` is the "What would you like to do?" heading. `problemTitle`, `ideaTitle` and `generalTitle` rename the type in the chooser and head its form (the General default heading is "How was your visit?" with stars, "General feedback" without). `messagePlaceholder` replaces the message placeholder for all three types. `confirmation` replaces "Thanks! We've got it." (not the offline "Saved for later"). |
+
+History wrapping follows the same rules as the `fetch` wrapping: the original
+always runs with the caller's arguments and its return value is passed back,
+our callback can't throw into the page, it's only installed when `hidePaths`
+is non-empty and the button isn't hidden anyway, and `destroy()` restores the
+originals unless something else wrapped them on top of us.
+
+## Known issues
+
+A team can mark an open report "Show to visitors" with a public title they
+write. The config then lists it in `known` (`{ id, title, paths, signature }`,
+up to 20, newest first; missing on older APIs, which means none). A known
+issue matches this page view when one of its `paths` is the current path
+(`/book` and `/book/` are the same page, as in fix checks; `*` is not
+special) or when its error `signature` showed up in this page view's
+console errors or failed requests (the fix-check signatures, every page view,
+no sampling; `src/known.ts`). Nothing is sent while watching.
+
+When the panel opens and something matches, it starts on a card above the
+type chooser: "We know about this", up to 3 public titles, and a **Me too**
+button for each (`POST /v1/widget/:key/known/:id/me-too {}`). After it:
+"Thanks, we've added you." (announced through the panel's live region) and,
+with `knownIssues.notify`, an "Email me when it's fixed" field and **Send**
+(the same request with `{ email }`). "Report something else" leaves the card
+for the normal flow (straight to the form when the site has one type). It
+works with `hideButton` through `open()`. A report already under way (a note
+typed) isn't interrupted by the card.
+
+## Visitor consent
+
+On sites that ask visitors for cookie consent (EU and UK cookie rules, and
+CNIL's guidance on session replay), the widget waits for the visitor to
+agree before anything beyond the button and its settings leaves the
+browser, or before replay starts at all. A page waits when the site's
+`settings.consent.required` is on ("Wait for visitor consent" in the
+dashboard), or when the script tag says `data-consent="wait"` (`init({
+consent: 'wait' })`). `data-consent="none"` makes a page not wait whatever
+the setting. Sites that don't wait behave exactly as before.
+
+Two parts, given with `Pinax.consent()`:
+
+- `diagnostics`: technical logs (console, failed requests and breadcrumbs)
+  attached to reports, fix checks (AI-17) and error counts (AI-20, with the
+  basket, AI-21), the Segment user id read when a report is sent, and the
+  page-view count (B-16).
+- `replay`: the session recorder (AI-15).
+
+| While the page waits | Without consent | With consent |
+|---|---|---|
+| Console, network and breadcrumb capture | Keeps running, in memory only: nothing leaves the browser | The same |
+| Logs on a report | Only if the visitor ticks "Include technical details" in the form | Attached (as far as the site's capture settings allow, C-10) |
+| Fix checks, error counts | Not started | Started once; `POST /fix-check` and `/sighting` carry `consent: true` (see The flags) |
+| Segment user id on a report | Not read | Read, as before |
+| Page-view count | Not sent | One `POST {cdn}/count/{key}` per page load (`POST {api}/v1/widget/{key}/count` without a CDN): no body, no cookies, `keepalive` |
+| Session replay | Not started; stopped, and its 30 seconds dropped, when consent is withdrawn | Started if this page view was in the sample |
+
+- **Withdrawing** (`consent(false)`, or `{ replay: false }`) stops the fix
+  checks and error counts and stops the recorder, dropping what it held.
+  Given again, they start again; errors from before are never sent twice.
+- **The replay sample** is drawn once per page view, when the settings
+  arrive, so consent given later still follows `replaySampleRate`.
+- **Reports** still work without consent: the note, the screenshot, the page
+  address and the browser details. The body carries `consent: { diagnostics,
+  replay }` and `includeLogs: true` when the box was ticked; the API drops
+  logs and the replay that weren't agreed to, as a second line of defence.
+- **The flags** (`consent` on reports, `consent: true` on fix checks and
+  error counts) go wherever the page waits *or* the site's setting does,
+  with what is actually allowed. The API goes by the site's setting alone,
+  so on a site that waits, `data-consent="none"` sends everything as agreed
+  (both `true`) rather than having it dropped. Sites that don't wait, with
+  no override, send no flags.
+- **The count**: on these sites the CDN doesn't count the settings request
+  (`cdn/README.md`); the widget counts the page load once the visitor
+  agrees. It follows the site's setting, like the CDN, so with a
+  `data-consent` override a page load is never counted twice or not at all.
+- **Before `pinax.js` loads**, calls wait in the stub queue (below) and are
+  replayed in order. `consent()` before `init()` is kept, like `identify()`;
+  `destroy()` forgets it.
+
+### The form's notice
+
+Above Send, every form says what goes with the note, listing only what will
+actually be attached:
+
+> Sent to harbourcafe.co.uk with your note: the page address, your browser
+> details, the screenshot, technical logs, a recording of the last 30
+> seconds. [Privacy policy]
+
+The site is this page's host name (without `www.`); the screenshot,
+technical logs and recording appear only when they'll go. With `privacyUrl`
+set, "Privacy policy" links it (new tab, `rel="noopener noreferrer"`). Send
+is described by the notice (`aria-describedby`), so screen readers read it
+with the button.
+
+The screenshot "Report a problem" takes on its own is only in the visitor's
+browser until Send: **Remove** under it (named "Remove screenshot" for screen
+readers) drops it, and the notice stops listing it. The optional email field
+says what the address is for and nothing more: "Only used to tell you about
+this report." on problems, "Only used to reply to you about this." on the
+other types, and "Only used to tell you when it's fixed." under a known
+issue's "Email me when it's fixed".
+
+While the page waits and the visitor hasn't given `diagnostics`, and console
+or network capture is on, an **unticked** checkbox sits above the notice:
+"Include technical details (console messages and failed requests) to help
+fix this". Ticking it adds "technical logs" to the notice and sends the logs
+with this report (`includeLogs: true`). It's a native, labelled checkbox
+(Space toggles it). If consent changes while the form is open, the notice
+and the box update in place without disturbing what the visitor is typing.
+Nothing is attached that the notice didn't list.
+
+### Banner recipes
+
+Put the stub first, so `Pinax.consent()` calls from a banner that answers
+before `pinax.js` has loaded are queued:
+
+```html
+<script>
+window.Pinax = window.Pinax || { q: [] }; ['init','open','identify','consent'].forEach(function (m) { window.Pinax[m] = window.Pinax[m] || function () { window.Pinax.q.push([m, [].slice.call(arguments)]); }; });
+</script>
+<script src="https://cdn.getpinax.com/pinax.js" data-key="pk_..." async></script>
+```
+
+Then one of these, after the stub:
+
+**Cookiebot**
+
+```js
+window.addEventListener('CookiebotOnConsentReady', () => Pinax.consent({ diagnostics: Cookiebot.consent.statistics, replay: Cookiebot.consent.statistics }));
+```
+
+**OneTrust** (`C0002` is OneTrust's default Performance group; the id can
+differ in your OneTrust account)
+
+```js
+window.addEventListener('OneTrustGroupsUpdated', (e) => { const ok = e.detail.includes('C0002'); Pinax.consent({ diagnostics: ok, replay: ok }); });
+```
+
+**Usercentrics** (add "Pinax" as a service in Usercentrics first)
+
+```js
+window.addEventListener('UC_CONSENT', (e) => { const ok = !!e.detail.services['Pinax']?.consent?.given; Pinax.consent({ diagnostics: ok, replay: ok }); });
+```
+
+**Google Tag Manager**: a Custom HTML tag
+
+```html
+<script>Pinax.consent(true);</script>
+```
+
+with Consent Settings → "Require additional consent for tag to fire:
+`analytics_storage`", fired on the consent update event. A tag can't take
+consent back: withdrawal needs the banner's own event (`Pinax.consent(false)`)
+or a page reload.
+
+**Shopify**
+
+```js
+window.Shopify.loadFeatures([{ name: 'consent-tracking-api', version: '0.2' }], (err) => { if (err) return; const apply = () => { const ok = window.Shopify.customerPrivacy.analyticsProcessingAllowed(); Pinax.consent({ diagnostics: ok, replay: ok }); }; apply(); document.addEventListener('visitorConsentCollected', apply); });
+```
+
+**Anything else**
+
+```js
+Pinax.consent({ diagnostics: true, replay: true }); // the visitor agreed
+Pinax.consent(false);                               // refused or withdrew
+```
+
+With replay on, CNIL recommends naming it on the banner's first layer, for
+example: "We record your actions on this page to fix technical problems
+(session replay)."
+
+## Segment
+
+Sites that use Segment (analytics.js) can install Pinax alongside it and get
+the widget's events in Segment. Turn on "Send events to Segment" on the
+dashboard's Widget screen (setting `segment`), or force it per page with
+`data-segment="true"` on the script tag or `init({ key, segment: true })`.
+
+```html
+<!-- 1. Segment's own snippet, as Segment gives it to you -->
+<script>!function(){var analytics=window.analytics=window.analytics||[]; /* … */ analytics.load("YOUR_WRITE_KEY");analytics.page();}();</script>
+<!-- 2. Pinax, after it -->
+<script src="https://cdn.getpinax.com/pinax.js" data-key="pk_..." data-segment="true" async></script>
+```
+
+Loading Pinax through Segment instead (for example from a Segment-managed tag
+or after `analytics.ready`) works the same way: the widget only looks for
+`window.analytics` when something happens, so the order doesn't matter.
+
+| Event | Properties |
+|---|---|
+| `Pinax Widget Opened` | `source: "pinax"` |
+| `Feedback Submitted` | `source`, `type` (`problem`, `idea`, `general`), `rating` (when given), `reportId` (when sent), `queued: true` (saved offline) |
+
+Never sent: the message, the email, screenshots or anything else the visitor
+typed. If the site hasn't called `Pinax.identify()` with an `id`, reports use
+Segment's signed-in user id (`analytics.user().id()`) as the visitor's user
+ID (on pages that wait for consent, only once `diagnostics` is given);
+anonymous Segment visitors stay anonymous. Errors from Segment never reach
+the page.
+
+## Live preview (dashboard, S-03)
+
+`@getpinax/widget/preview` (`dist/preview.mjs`, ~10 KB gzipped with its shared
+chunk) renders the real button and panel into a container's shadow root from
+a settings object. It makes no API calls and installs nothing: no console,
+network or history wrapping, no screenshot library, no reports. "Send" just
+shows the confirmation; the problem form shows a placeholder screenshot.
+
+```ts
+import { preview } from '@getpinax/widget/preview';
+
+// The container needs a size; the widget is positioned inside it as it
+// would be in the visitor's window. Call only in the browser (useEffect).
+const p = preview(element, settings, { view: 'choose', phone: false, poweredBy: true });
+p.update(nextSettings);          // on every form change; keeps the screen on show
+p.update(nextSettings, { phone: true });
+p.show('idea');                  // 'button' | 'choose' | 'problem' | 'idea' | 'general' | 'done'
+p.view();                        // the screen on show (visitors can click around)
+p.destroy();
+```
+
+`settings` is the same shape as the backend's widget settings; any field may
+be left out. `known: [{ id, title, paths, signature }]` in the options shows
+the known issues card on the chooser as if they matched (the first 3); without
+it the card never shows in the preview. `site: 'harbourcafe.co.uk'` names the
+site in the form's notice ("Sent to … with your note", default "this
+website"); with `consent: { required: true }` in the settings the forms show
+the "Include technical details" box. `phone: true` shows the phone layout (bottom sheet,
+`smallOnMobile`) whatever the page width. `hidePaths` has no effect in the
+preview. The preview never moves focus, so it can update while the owner
+types. `playground/preview.html` is a working example.
+
+## Pinax AI in the browser (Phase 4)
+
+`GET /config` also returns `ai` (`widgetAiConfig` in
+`backend/src/modules/widget/widget.service.ts`); `resolveAi` (`src/settings.ts`)
+turns everything off when it's missing, and caps both sample rates at
+`samplingRate` (B-17).
+
+| Feature | What the widget does |
+|---|---|
+| AI-11 breadcrumbs | A ring buffer of the last 20 clicks, page views (load and SPA navigation) and "typed in field X" events, sent with every report (`src/capture/breadcrumbs.ts`). A target is its role plus its accessible name or text, cut to 60 characters: `button "Book a table"`, `link "Menu"`, `textbox "Email"`. Typed values are never read. Nothing is read from inside inputs, `contenteditable`, `[data-pinax-mask]` or `.pinax-mask`; password and card fields are just `password field` / `card field`. Paths keep the query's keys but not its values (`/search?q=…`) or the fragment; emails and phone numbers in a target are starred out when the report is sent. |
+| AI-10 follow-up | With `ai.followUp`, a problem or idea with a note of 140 characters or fewer calls `POST /follow-up` first (4 s timeout). A question shows as one more panel step ("One quick question", the note, the question as the answer field's label, **Send** and **Skip and send**). The answer goes in the report as `followUp`. On no question, an error or the timeout, the report is sent straight away. Asked once per note. |
+| AI-12 auto-blur | With `ai.autoBlur`, the editor chunk finds visible emails, phone numbers (UK and international) and likely names (after labels such as "Name", "Customer", "Guest name", "Booked by", "Signed in as", in a "Name" table column or `<dt>`, or in `autocomplete=name` / schema.org Person elements) and paints the same striped mask as form fields over them (`src/editor/pii.ts`, `src/privacy.ts`). The live page is never changed. The panel says "We blurred N private details for you." and the editor outlines them with an "Auto-blurred" tag; they're part of the image, so only the visitor's own Blur marks can be undone. |
+| AI-15 replay (Pro, Agency) | With `ai.replay` and a passing draw of `replaySampleRate` (once per page view), `pinax-recorder.js` (rrweb's `record`, MIT) is loaded after the page's `load` event (and, where the page waits for consent, once `replay` is given; see Visitor consent). It keeps a rolling 30 s in memory, in segments that each start with a full snapshot (checkout every 10 s), so at most 40 s is held. Always: inputs are masked (`maskAllInputs`), hidden inputs, `.pinax-mask` / `[data-pinax-mask]` and the widget are blocked, and attributes are cleaned on the way out (URL secrets, emails, phone numbers). `ai.replayMask` decides the rest: **`'all'`** (the default, also when the config doesn't say; CNIL's "mask everything") stars out every text and text attributes (`alt`, `title`, `aria-label`, `placeholder`, `value`…) and leaves out `img`, `picture`, `video`, `canvas` and `iframe` (the replay shows an empty box of the same size); **`'inputs'`** keeps the page's text, starring out editable text and emails and phone numbers in it. **Nothing is sent by the recorder.** When a report is sent, the buffer is gzipped (`CompressionStream`; no replay where it's missing), base64-encoded and added as `replay` if it fits 4.5 M characters and the whole request stays under 11 MB (fewer seconds are tried before giving up). |
+| AI-17 fix check (P-14) | For each `ai.fixChecks` entry whose `path` equals `location.pathname` (re-checked on SPA navigation), one draw of `fixCheckSampleRate` per page view. If it passes, this page view's console errors and failed requests (from the existing capture) are signed with the backend's own `errorSignature` (`src/capture/signature.ts`, ported exactly), and a match sends `POST /fix-check {checkId, signature}` once per check per page view. Nothing else is sent, and nothing on success. |
+
+## Privacy
+
+- Every form field (inputs, textareas, selects, contenteditable) is hidden in
+  screenshots, as is anything marked `data-pinax-mask` or `class="pinax-mask"`.
+  The live page is never changed: masking happens on the screenshot library's
+  private copy, and striped blocks are painted over the field positions.
+- The network log keeps only failed (status 0, 4xx, 5xx) and slow (over 2 s)
+  requests: method, URL, status, duration and time. Headers, cookies and
+  bodies are never read. URL fragments and credentials are dropped, and
+  every query value is replaced with `…` (`/api/orders?email=…&page=…`):
+  the keys stay, so the team can still see what was asked.
+- The page address on a report keeps only the values of `utm_*`, `page`,
+  `lang`, `ref`, `variant`, `tab` and `sort`; every other value is `…`
+  (`/search?q=…&page=2`), and there's no fragment. The `?pinax_verify` ping
+  sends the address the same way.
+- Console messages and stacks have emails and phone numbers starred out
+  (`redactPersonal`, `src/privacy.ts`) when a report is built. The error
+  signature that fix checks and error counts compare is made from the
+  starred-out text too, so it never carries them (it's published in the
+  site's settings).
+- The API applies all of these again (`widget.sanitise.ts`), for older
+  cached widgets.
+- No keystrokes are recorded. Pinax's own requests never appear in the log.
+- A report that can't be sent (offline, or a server error; W-16) waits in
+  `localStorage` (`pinax:queue:<key>`) for an hour at most, without the
+  email address, `identify()` data, console log, screenshot or replay. The
+  email and `identify()` data stay in the page's memory and go with a retry
+  from the same page only; after a reload the report goes without them, and
+  the "Saved for later" screen says so when an email was given. A report is
+  removed once it's sent or refused for good, and anything older than an
+  hour is deleted unsent the next time the widget loads (`src/queue.ts`).
+- Breadcrumbs and the replay follow the same masking rules; see the table above.
+- On sites that wait for visitor consent, logs, error counts, the page-view
+  count and the replay wait for it (see Visitor consent).
+
+## How it loads
+
+| File | Gzipped | When |
+|---|---|---|
+| `dist/pinax.js` | ~23 KB | The script tag. Button, panel, capture. Limit 50 KB (W-13). |
+| `dist/pinax-editor.js` | ~17 KB | ES module loaded with `import()` from the same folder as `pinax.js`, only when a visitor takes a screenshot. Screenshot capture (`modern-screenshot`, MIT), auto-blur and the annotation editor. |
+| `dist/pinax-recorder.js` | ~27 KB | ES module loaded the same way, after page load, only on sampled Pro/Agency visits with replay on (after consent where the page waits for it). Session recorder (`@rrweb/record`, MIT). |
+| `dist/pinax.mjs` + `dist/chunks/` | | npm build. The editor is a normal dynamic-import chunk. |
+| `dist/preview.mjs` + `dist/chunks/` | ~10 KB | `@getpinax/widget/preview`, the dashboard's live preview. Shares the UI chunk with `pinax.mjs`. |
+
+`pinax-editor.js` and `pinax-recorder.js` must be served next to `pinax.js`
+with CORS allowed (they are ES module imports). On page load the widget makes
+one request, for the site's settings from the CDN
+(`https://cdn.getpinax.com/config/<key>.json`, P-15), plus `POST /ping` only
+when the URL has `?pinax_verify`, a retry only when this visitor has a
+report waiting from an earlier offline send (W-16), and, on sites that wait
+for visitor consent, one `POST /count/<key>` once the visitor agrees. It asks the API
+(`GET /v1/widget/<key>/config`) only when the CDN can't answer, or when there's
+no CDN (local builds, or `apiUrl`/`data-api` set without `cdnUrl`/`data-cdn`).
+
+### The CDN (P-15, B-16)
+
+`cdn/` is the Cloudflare Worker behind `cdn.getpinax.com`; see
+[`cdn/README.md`](cdn/README.md). In short: `pinax.js` is cached for an hour
+(the URL customers paste never changes), `?v=<version>` files for a year as
+immutable, and each site's settings are static JSON the API republishes on
+every change, revalidated by browsers on each page load so the edge can count
+it as a page view (B-16) without the API ever being called. Sites that wait
+for visitor consent are counted by `POST /count/<key>` instead, after consent.
+
+## Accessibility and touch (W-12, W-15)
+
+`src/__tests__/a11y.test.ts` runs axe-core (WCAG 2.0 to 2.2 A and AA, plus
+best practice) on every panel screen, the follow-up question and the
+screenshot editor, and checks text contrast (4.5:1), non-text contrast (3:1)
+and target sizes (24 px, 2.5.8) from the CSS. `annotator.test.ts` drives the
+editor with touch, pen and mouse pointer events, the keyboard fallbacks
+(Enter on the image places a mark or selects the middle area; Ctrl/Cmd+Z;
+Escape; focus stays inside) and area selection (W-04).
+
+jsdom has no layout or real touch, so these still need a person with a device
+before each release:
+
+- iPhone (Safari) and Android (Chrome): open the panel, take a screenshot,
+  draw a box, an arrow and a blur with a finger, select an area, send. The
+  page mustn't scroll or zoom while drawing, and focusing a field mustn't
+  zoom the page.
+- iPad (Safari) in both orientations, plus Apple Pencil.
+- iOS screenshots: pages with cross-origin images or fonts without CORS
+  headers show those images as grey blocks and fall back to system fonts (a
+  browser rule; nothing the widget can fix). Captures are capped at 2560 px
+  on the long side and 5 MP in total (`captureScale`), well under iOS
+  Safari's 16.7 MP canvas limit, and the editor frees its scratch canvas.
+- VoiceOver (iOS and macOS) and NVDA (Windows): open with the keyboard, hear
+  the dialog name, choose a type, hear errors and the confirmation, use the
+  editor without a pointer.
+- 200% and 400% zoom, and Windows high contrast (forced colours).
+
+## Development
+
+```bash
+yarn dev            # http://localhost:5175 (index.html, ES module from src/)
+yarn playground     # build, then http://localhost:5177/playground/embed.html (the built script tag)
+                    #   and /playground/preview.html (the dashboard preview). PORT=5176 to change the port.
+yarn build          # types, four bundles, declarations, size check
+yarn test           # vitest (jsdom)
+yarn run check      # biome. Plain `yarn check` is Yarn's own command.
+```
+
+**Accessibility checks (dev).** `yarn dev` adds an "Accessibility (dev)" panel
+(`playground/a11y-check.js`, never shipped). "Check the widget" steps through
+every screen (button, chooser, each form, thanks) and runs axe-core inside the
+shadow root in a real browser, so colour contrast and target size are measured
+rather than read from the CSS as in `src/__tests__/a11y.test.ts` (W-15). It
+uses `globalThis.__pinaxDevUI`, set in `src/index.ts` only when
+`import.meta.env.DEV` (Vite drops it from builds). "Scan this page" runs the
+scan an accessibility report attaches (W-20, `src/a11y/scan.ts`). Both
+playground pages have a "Broken on purpose" card with six failing controls
+(label, select name, image alt, link and button names, contrast) for trying
+accessibility reports; the site needs `types.accessibility` on.
+
+Both playground pages take `?key=pk_...` (and `?api=...`). They also have
+"Pinax AI switches" (`playground/fake-ai.js`): because a local backend has no
+model key, they patch the config in the page to turn on the follow-up
+question (with a canned question), force auto-blur, turn replay off, or add
+a known issue on the current page (tied to the "console.error" button's
+error, its Me too answered in the page). The
+widget code is unchanged; the switches wrap the page's `fetch` before the
+widget loads. `index.html` also
+reads `VITE_PINAX_KEY` from `.env.local`. To get a key, sign up through the
+API and create a website for `http://localhost:5175`; its allowed domain is
+`localhost`, which covers every port.
+
+The report body is built in `src/report.ts` to the limits in
+`backend/src/modules/widget/widget.validator.ts`. When `backend/` is checked
+out next to `widget/`, `report.test.ts` also checks the body against that
+real schema.

package/dist/a11y/scan.d.ts

@@ -0,0 +1,25 @@
+import axe from 'axe-core';
+import type { A11yScan } from '../types';
+export declare const SCAN_LIMITS: {
+    readonly violations: 50;
+    readonly nodes: 5;
+    readonly target: 300;
+    readonly html: 300;
+    readonly summary: 500;
+    readonly help: 300;
+};
+/** "wcag143" → "1.4.3", "wcag2aa" → null. */
+export declare function wcagCriterion(tag: string): string | null;
+/**
+ * The element's opening tag only: no text inside it, no typed values and
+ * no data attributes, with emails and phone numbers starred out.
+ */
+export declare function describeElement(el: Element | undefined | null): string;
+/**
+ * Runs axe-core on the page, leaving out the widget itself (`exclude`, the
+ * shadow host's selector). Resolves to null if axe fails.
+ */
+export declare function scanPage(options?: {
+    exclude?: string;
+}): Promise<A11yScan | null>;
+export declare function summarise(result: axe.AxeResults, durationMs: number): A11yScan;

package/dist/api.d.ts

@@ -0,0 +1,83 @@
+import { type ReportBody } from './report';
+import type { PinaxBasket, WidgetConfig } from './types';
+/**
+ * The API origin. Production builds set VITE_PINAX_API (e.g. the real API
+ * domain); without it the widget talks to a local backend. `data-api` on the
+ * script tag, or `apiUrl` in init(), still overrides this per site.
+ */
+export declare const DEFAULT_API: string;
+export declare function apiBase(apiUrl?: string): string;
+/**
+ * P-15: the CDN origin that serves each site's settings as static JSON
+ * (`/config/<key>.json`). Production builds set VITE_PINAX_CDN; without it
+ * (local builds) settings come straight from the API.
+ */
+export declare const DEFAULT_CDN: string;
+/**
+ * Where settings come from: `cdnUrl` / `data-cdn` if given; otherwise the
+ * build's CDN, unless the API was overridden (a local or self-hosted API has
+ * no CDN in front of it). Null means "ask the API".
+ */
+export declare function cdnBase(cdnUrl?: string, apiUrl?: string): string | null;
+export declare function cdnConfigUrl(cdn: string, key: string): string;
+/**
+ * The fetch the widget itself uses: the page's fetch as it was before Pinax
+ * wrapped it, so Pinax's own calls never show up in the network log.
+ */
+export type Fetch = typeof fetch;
+/**
+ * P-15: settings from the CDN, so a page load never reaches our servers.
+ * The API is asked only when there's no CDN, or the CDN can't answer
+ * (down, blocked, or not set up yet).
+ */
+export declare function fetchConfig(doFetch: Fetch, api: string, key: string, cdn?: string | null): Promise<WidgetConfig | null>;
+/** S-12: only when the owner opens their site with ?pinax_verify. */
+export declare function pingIfVerifying(doFetch: Fetch, api: string, key: string, href: string): void;
+export type SendResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    retry: boolean;
+    status: number;
+    message: string;
+};
+export declare function sendReport(doFetch: Fetch, api: string, key: string, body: ReportBody): Promise<SendResult>;
+/** AI-10: the follow-up question gets this long before the report goes without it. */
+export declare const FOLLOW_UP_TIMEOUT_MS = 4000;
+/**
+ * AI-10: asks the backend whether a short note needs one follow-up question.
+ * Resolves to null on any error or after the timeout, so sending never
+ * waits longer than that.
+ */
+export declare function fetchFollowUp(doFetch: Fetch, api: string, key: string, input: {
+    type: string;
+    message: string;
+    pagePath: string;
+}, timeoutMs?: number): Promise<string | null>;
+/**
+ * AI-17: the watched error came back on a page marked Fixed; AI-20
+ * (`'sighting'`): an open report's error showed up. Fire and forget; only
+ * the report id and the signature are sent (P-14, P-17). `consent: true`
+ * only on sites that wait for consent, once the visitor agreed.
+ */
+export declare function sendFixCheck(doFetch: Fetch, api: string, key: string, hit: {
+    checkId: string;
+    signature: string;
+    basket?: PinaxBasket;
+    consent?: boolean;
+}, kind?: 'fix-check' | 'sighting'): void;
+/** Where the page-view count goes: the CDN, or the API when there's none. */
+export declare function countUrl(api: string, key: string, cdn: string | null): string;
+/**
+ * B-16 on sites that wait for consent: the settings request isn't counted
+ * there, so once the visitor agrees, this page load is counted with one
+ * empty POST (no body, no cookies). Fire and forget.
+ */
+export declare function sendCount(doFetch: Fetch, api: string, key: string, cdn: string | null): void;
+/**
+ * Known issues: "Me too" on a public report, with an email to hear when
+ * it's fixed. Sending the email after a Me too repeats the call; the API
+ * counts each visitor once and keeps the email.
+ */
+export declare function sendMeToo(doFetch: Fetch, api: string, key: string, id: string, email?: string): Promise<boolean>;