@getpinax/widget 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -13,11 +13,14 @@ npm install @getpinax/widget
 ```
 
 ```ts
-import { init, open, identify, destroy } from '@getpinax/widget';
+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
@@ -49,36 +52,66 @@ 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`) and `cdnUrl` (default `https://cdn.getpinax.com`,
-where the site's settings are read from, P-15). With only `apiUrl` set,
-settings come from that API, which is what you want for a local backend.
+`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-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
 
-`npm publish` runs `prepublishOnly`: the production build (with
-`VITE_PINAX_API=https://api.getpinax.com` and
-`VITE_PINAX_CDN=https://cdn.getpinax.com` baked in), the tests and the size
-check. The package ships `dist/` only. Bump `version` first; it's also the
-`?v=` the script tag uses to load matching editor and recorder files from the CDN.
+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? })` | 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. |
+| `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 to reports (C-09). Works before `init`. The email also pre-fills the form. |
+| `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`
@@ -93,6 +126,10 @@ malformed falls back to the defaults (`src/settings.ts`).
 | `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
@@ -101,6 +138,171 @@ 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
@@ -127,7 +329,8 @@ or after `analytics.ready`) works the same way: the widget only looks for
 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; anonymous Segment visitors stay anonymous. Errors from Segment never reach
+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)
@@ -152,7 +355,12 @@ p.destroy();
 ```
 
 `settings` is the same shape as the backend's widget settings; any field may
-be left out. `phone: true` shows the phone layout (bottom sheet,
+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.
@@ -166,10 +374,10 @@ turns everything off when it's missing, and caps both sample rates at
 
 | 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 (secrets masked) but not the fragment. |
+| 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`, `pinax-recorder.js` (rrweb's `record`, MIT) is loaded after the page's `load` event. 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. Inputs are masked (`maskAllInputs`), `.pinax-mask` / `[data-pinax-mask]` and the widget are blocked, editable text is starred out and emails and phone numbers in page text are starred out. **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-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
@@ -180,18 +388,40 @@ turns everything off when it's missing, and caps both sample rates at
   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. Secret-looking query values are replaced with
-  `[hidden]` and URL fragments are dropped.
+  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` | ~17 KB | The script tag. Button, panel, capture. Limit 50 KB (W-13). |
+| `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` | ~26 KB | ES module loaded the same way, after page load, only on sampled Pro/Agency visits with replay on. Session recorder (`@rrweb/record`, MIT). |
+| `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`. |
 
@@ -199,8 +429,9 @@ turns everything off when it's missing, and caps both sample rates at
 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`, and a retry only when this visitor has a
-report waiting from an earlier offline send (W-16). It asks the API
+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`).
 
@@ -211,7 +442,8 @@ no CDN (local builds, or `apiUrl`/`data-api` set without `cdnUrl`/`data-cdn`).
 (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.
+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)
 
@@ -252,10 +484,24 @@ 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, or turn replay off. The
+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

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

@@ -1,5 +1,5 @@
-import type { ReportBody } from './report';
-import type { WidgetConfig } from './types';
+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
@@ -55,8 +55,29 @@ export declare function fetchFollowUp(doFetch: Fetch, api: string, key: string,
     message: string;
     pagePath: string;
 }, timeoutMs?: number): Promise<string | null>;
-/** AI-17: the watched error came back on a page marked Fixed. Fire and forget. */
+/**
+ * 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;
-}): void;
+    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>;

package/dist/capture/breadcrumbs.d.ts

@@ -30,7 +30,7 @@ export declare function nameOf(el: Element): string;
  * only its role or tag: its text may be the visitor's own details.
  */
 export declare function describeTarget(start: Element): string;
-/** The page as breadcrumbs record it: path and query, secrets masked, no fragment. */
+/** The page as breadcrumbs record it: path and query keys (values hidden), no fragment. */
 export declare function currentPath(href?: string): string;
 type Options = {
     /** Events from inside the widget itself are left out. */

package/dist/capture/network.d.ts

@@ -16,7 +16,7 @@ type Options = {
 };
 /**
  * C-05/C-06: wraps fetch and XMLHttpRequest and records only failed or slow
- * requests: method, URL (secrets masked), status (0 = network error),
+ * requests: method, URL (query values hidden), status (0 = network error),
  * duration and time. Headers and bodies are never read.
  */
 export declare function captureNetwork(buffer: RingBuffer<NetworkEntry>, target?: Window, options?: Options): () => void;

package/dist/capture/signature.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Emails and phone numbers are starred out first, as in the report's console
+ * text, so a signature never carries them (it's published in the site's
+ * config) and matches whether the text was starred out already or not.
+ */
 export declare function normalise(text: string): string;
 export declare function errorSignature(consoleLogs: unknown, networkLogs: unknown): string | null;

package/dist/capture/text.d.ts

@@ -2,6 +2,22 @@
 export declare function clip(value: string, max: number): string;
 /**
  * C-06: drops the fragment, credentials and secret-looking query values from a
- * URL before it is kept. The backend masks again (defence in depth).
+ * URL before it is kept. The backend masks again (defence in depth). For
+ * what is sent, `logUrl` and `pageUrl` (report.ts) also hide query values.
  */
 export declare function safeUrl(raw: string, base?: string): string;
+/**
+ * Query parameters whose values a report's page address keeps: campaign and
+ * view state, never anything a visitor typed. Everything else becomes `…`.
+ * Mirrors `PAGE_PARAM` in `backend/src/modules/widget/widget.sanitise.ts`.
+ */
+export declare const PAGE_PARAM: RegExp;
+/**
+ * Personal data hides in query strings (`?email=`, `?name=`, search terms),
+ * so every value becomes `…` and only the keys stay, except those `keep`
+ * names. Works on the string, so `…` isn't percent-encoded, and keys,
+ * order and key-only parameters (`?debug`) are kept as they were.
+ */
+export declare function maskQuery(url: string, keep?: RegExp): string;
+/** Network log and breadcrumb URLs: `safeUrl`, then every query value hidden. */
+export declare function logUrl(raw: string, base?: string): string;