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

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,268 @@
-# 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, destroy } from '@getpinax/widget';
+
+// Once, as early as you like (e.g. in your app's entry file). Browser only.
+init({ key: 'pk_...' });
+
+// 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`) 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.
+
+### 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 -->
+```
+
+### 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.
+
+## 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. |
+| `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. |
+| `destroy()` | Removes the widget and restores `console`, `fetch` and `XMLHttpRequest`. |
+
+With the script tag these are on `window.Pinax`.
+
+## 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. |
+| `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.
+
+## 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; 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. `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 (secrets masked) but not the fragment. |
+| 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-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. Secret-looking query values are replaced with
+  `[hidden]` and URL fragments are dropped.
+- No keystrokes are recorded. Pinax's own requests never appear in the log.
+- Breadcrumbs and the replay follow the same masking rules; see the table above.
+
+## How it loads
+
+| File | Gzipped | When |
+|---|---|---|
+| `dist/pinax.js` | ~17 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.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`, and a retry only when this visitor has a
+report waiting from an earlier offline send (W-16). 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.
+
+## 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.
+```
+
+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
+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/api.d.ts

@@ -0,0 +1,62 @@
+import type { ReportBody } from './report';
+import type { 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. Fire and forget. */
+export declare function sendFixCheck(doFetch: Fetch, api: string, key: string, hit: {
+    checkId: string;
+    signature: string;
+}): void;

package/dist/capture/breadcrumbs.d.ts

@@ -0,0 +1,49 @@
+import type { RingBuffer } from './ring';
+/**
+ * AI-11: what the visitor did just before sending. The backend's schema is
+ * `breadcrumbs` in `backend/src/modules/widget/widget.validator.ts`.
+ */
+export type Breadcrumb = {
+    kind: 'click' | 'navigation' | 'input';
+    at: string;
+    path: string;
+    /** Short, privacy-safe description of the target, e.g. button "Book a table". */
+    target?: string;
+};
+export declare const MAX_BREADCRUMBS = 20;
+export declare const MAX_NAME = 60;
+/** A password or payment card field: not even its label is kept. */
+export declare function isSecretField(el: Element): boolean;
+export declare function roleOf(el: Element): string;
+/**
+ * Visible text of `el`, skipping form fields, editable areas and anything
+ * the owner masked. Images contribute their alt text.
+ */
+export declare function safeText(el: Element, max?: number): string;
+/** The accessible name, as far as it can be read without visitor data. */
+export declare function nameOf(el: Element): string;
+/**
+ * A short, privacy-safe description of what was clicked or typed in:
+ * `button "Book a table"`, `link "Menu"`, `textbox "Email"`,
+ * `password field`. Names are cut to 60 characters. A click on anything
+ * that isn't a control (a paragraph, a table cell, an order summary) keeps
+ * 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. */
+export declare function currentPath(href?: string): string;
+type Options = {
+    /** Events from inside the widget itself are left out. */
+    ignore?: (target: EventTarget | null) => boolean;
+    doc?: Document;
+};
+/**
+ * Records clicks and typing (never what was typed) into `buffer`. Page views
+ * are added by the caller through `navigated()`, so they share the one
+ * history watcher. Never throws into the page.
+ */
+export declare function captureBreadcrumbs(buffer: RingBuffer<Breadcrumb>, options?: Options): {
+    navigated: () => void;
+    stop: () => void;
+};
+export {};

package/dist/capture/console.d.ts

@@ -0,0 +1,17 @@
+import type { RingBuffer } from './ring';
+export type ConsoleLevel = 'error' | 'warn' | 'log' | 'info' | 'debug';
+export type ConsoleEntry = {
+    level: ConsoleLevel;
+    message: string;
+    stack?: string;
+    at: string;
+};
+export declare const MAX_MESSAGE = 2000;
+export declare const MAX_STACK = 4000;
+export declare function formatArgs(args: unknown[]): string;
+/**
+ * C-04: wraps console methods and listens for uncaught errors and rejected
+ * promises. Never throws into the page; if the host replaces `console` later,
+ * capture just stops for the replaced methods.
+ */
+export declare function captureConsole(buffer: RingBuffer<ConsoleEntry>, target?: Window & typeof globalThis): () => void;

package/dist/capture/env.d.ts

@@ -0,0 +1,25 @@
+import { type DeviceType } from './ua';
+export type Environment = {
+    userAgent: string;
+    browser?: string;
+    browserVersion?: string;
+    os?: string;
+    deviceType: DeviceType;
+    deviceModel?: string;
+    screen: {
+        w: number;
+        h: number;
+    };
+    viewport: {
+        w: number;
+        h: number;
+    };
+    pixelRatio: number;
+    timeZone: string;
+    language?: string;
+    occurredAt: string;
+};
+/** Local time with its UTC offset, e.g. 2026-11-04T15:20:01.123+01:00 (C-01). */
+export declare function localIsoTime(date?: Date): string;
+/** C-01 to C-03, read at the moment the visitor sends. */
+export declare function readEnvironment(win?: Window): Environment;

package/dist/capture/network.d.ts

@@ -0,0 +1,23 @@
+import type { RingBuffer } from './ring';
+export type NetworkEntry = {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    at: string;
+};
+/** C-05: a request is kept when it fails or takes longer than this. */
+export declare const SLOW_MS = 2000;
+export declare function shouldRecord(status: number, durationMs: number): boolean;
+type Options = {
+    /** Requests to these URL prefixes (Pinax's own API) are never recorded. */
+    ignore?: (url: string) => boolean;
+    now?: () => number;
+};
+/**
+ * C-05/C-06: wraps fetch and XMLHttpRequest and records only failed or slow
+ * requests: method, URL (secrets masked), 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;
+export {};

package/dist/capture/ring.d.ts

@@ -0,0 +1,14 @@
+/** A fixed-size buffer that keeps only the newest `capacity` items (C-04, C-05). */
+export declare class RingBuffer<T> {
+    readonly capacity: number;
+    private items;
+    private listeners;
+    constructor(capacity: number);
+    push(item: T): void;
+    /** Called with every new item (AI-17 fix check). Returns an unsubscribe. */
+    subscribe(listener: (item: T) => void): () => void;
+    /** Oldest first. Returns a copy. */
+    toArray(): T[];
+    clear(): void;
+    get size(): number;
+}

package/dist/capture/signature.d.ts

@@ -0,0 +1,2 @@
+export declare function normalise(text: string): string;
+export declare function errorSignature(consoleLogs: unknown, networkLogs: unknown): string | null;

package/dist/capture/text.d.ts

@@ -0,0 +1,7 @@
+/** Cuts a string to `max` characters, marking the cut with an ellipsis. */
+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).
+ */
+export declare function safeUrl(raw: string, base?: string): string;

package/dist/capture/ua.d.ts

@@ -0,0 +1,13 @@
+export type DeviceType = 'desktop' | 'mobile' | 'tablet';
+export type ParsedUA = {
+    browser?: string;
+    browserVersion?: string;
+    os?: string;
+    deviceType: DeviceType;
+    deviceModel?: string;
+};
+/**
+ * C-02: a small hand-written user-agent parser. `maxTouchPoints` tells iPads
+ * in desktop mode (which claim to be a Mac) apart from real Macs.
+ */
+export declare function parseUserAgent(ua: string, maxTouchPoints?: number): ParsedUA;