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

package/dist/editor/annotator.d.ts

@@ -0,0 +1,20 @@
+import type { Annotation } from '../types';
+import type { Rect } from './mask';
+import { type Shape } from './shapes';
+export type EditState = {
+    shapes: Shape[];
+    area: Rect | null;
+};
+export type EditResult = {
+    canvas: HTMLCanvasElement;
+    annotations: Annotation[];
+    state: EditState;
+};
+/**
+ * W-04 to W-06, W-12: full-screen editor over the screenshot. Pointer events
+ * cover mouse, touch and pen; a tap (or Enter on the focused image) places a
+ * default-size mark, so drawing never needs a drag (WCAG 2.5.7).
+ */
+export declare function annotate(root: ShadowRoot, base: HTMLCanvasElement, initial?: EditState, 
+/** AI-12: areas blurred automatically. Baked into `base`; shown, never removable. */
+auto?: Rect[]): Promise<EditResult | null>;

package/dist/editor/capture.d.ts

@@ -0,0 +1,28 @@
+import { type Rect } from './mask';
+/** Longest side of the captured image, in pixels. */
+export declare const MAX_SIDE = 2560;
+/**
+ * W-12: most pixels in one capture. iOS Safari refuses canvases over 16.7 M
+ * pixels and has a small total canvas memory budget (the editor holds about
+ * four canvases of this size), so stay well under it on every device.
+ */
+export declare const MAX_PIXELS = 5000000;
+/** Pixel scale for a viewport: device pixels up to 2x, within both caps. */
+export declare function captureScale(viewport: {
+    w: number;
+    h: number;
+}, devicePixelRatio: number): number;
+export type Capture = {
+    canvas: HTMLCanvasElement;
+    /** AI-12: areas blurred automatically, in image pixels. */
+    auto: Rect[];
+};
+/**
+ * W-03: an image of what the visitor can see right now. The widget itself
+ * (`exclude`) is left out, form fields and owner-marked elements are masked
+ * (C-07), and the live page is never modified. With `autoBlur` (AI-12),
+ * emails, phone numbers and likely names in the page text are masked too.
+ */
+export declare function captureViewport(exclude: Element | null, win?: Window, options?: {
+    autoBlur?: boolean;
+}): Promise<Capture>;

package/dist/editor/encode.d.ts

@@ -0,0 +1,7 @@
+/** Aim well under the backend's 4.5 MB so reports upload quickly on phones. */
+export declare const TARGET_BYTES: number;
+/**
+ * The flattened image as WebP (JPEG where WebP encoding isn't supported, as
+ * in older Safari), lowering quality and then size until it fits.
+ */
+export declare function encodeCanvas(source: HTMLCanvasElement, target?: number): string;

package/dist/editor/index.d.ts

@@ -0,0 +1,5 @@
+import type { Shot } from '../ui/widget';
+export declare function takeScreenshot(exclude: Element | null, options?: {
+    autoBlur?: boolean;
+}): Promise<Shot>;
+export declare function markUp(root: ShadowRoot, shot: Shot): Promise<Shot | null>;

package/dist/editor/mask.d.ts

@@ -0,0 +1,29 @@
+/**
+ * C-07/C-08: what is hidden in screenshots. Every form field is masked
+ * (passwords and card fields included), plus anything the owner marks with
+ * `data-pinax-mask` or the `pinax-mask` class. Button-like inputs stay
+ * visible because they carry no visitor data.
+ */
+export declare const MASK_SELECTOR: string;
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare function isMasked(el: Element): boolean;
+/**
+ * Viewport rectangles of every masked element that is on screen, read from
+ * the live page (which is never changed).
+ */
+export declare function collectMaskRects(doc: Document, viewport: {
+    w: number;
+    h: number;
+}, exclude?: Element | null): Rect[];
+/**
+ * Applied to each node of the screenshot library's private copy of the page,
+ * so typed values never reach the image even before the masks are painted.
+ */
+export declare function maskClone(node: Node): void;
+/** Paints the board's striped "hidden" pattern over each rectangle. */
+export declare function paintMasks(ctx: CanvasRenderingContext2D, rects: Rect[], scale: number): void;

package/dist/editor/pii.d.ts

@@ -0,0 +1,22 @@
+import { type Rect } from './mask';
+/**
+ * AI-12: personal details in the visible page text, found before the
+ * screenshot is taken. Everything here only reads the live page; the
+ * capture paints over what it finds.
+ */
+export type PrivateHit = {
+    node: Text;
+    start: number;
+    end: number;
+    reason: 'email' | 'phone' | 'name';
+} | {
+    element: Element;
+    reason: 'name';
+};
+/** Every email, phone number and likely name in the page's text. */
+export declare function findPrivateText(doc: Document, exclude?: Element | null): PrivateHit[];
+/** On-screen rectangles of the hits, in viewport pixels, padded a little. */
+export declare function privateRects(doc: Document, viewport: {
+    w: number;
+    h: number;
+}, exclude?: Element | null): Rect[];

package/dist/editor/shapes.d.ts

@@ -0,0 +1,31 @@
+import type { Annotation } from '../types';
+import type { Rect } from './mask';
+export type Tool = 'box' | 'arrow' | 'text' | 'blur';
+/** In image pixels. For an arrow, (x, y) is the tail and (x + w, y + h) the head. */
+export type Shape = {
+    type: Tool;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text?: string;
+};
+export declare const RED = "#FF5C35";
+export declare const LABEL_BG = "#CC3F1B";
+/** A box/blur with any drag direction, as a positive rectangle. */
+export declare function normalise(s: Shape): Shape;
+export declare function lineWidth(imgW: number, imgH: number): number;
+export declare function fontSize(imgW: number, imgH: number): number;
+/** Measures a text label so its box is known before it's drawn. */
+export declare function measureLabel(ctx: CanvasRenderingContext2D, text: string, size: number): {
+    w: number;
+    h: number;
+    pad: number;
+};
+/** Draws one shape. Blur is pixelated from `base`, so nothing underneath survives. */
+export declare function drawShape(ctx: CanvasRenderingContext2D, shape: Shape, base: CanvasImageSource, imgW: number, imgH: number): void;
+/** Shapes as the report's `annotations`: fractions of the sent (cropped) image. */
+export declare function toAnnotations(shapes: Shape[], area: Rect, measure: (s: Shape) => {
+    w: number;
+    h: number;
+}): Annotation[];

package/dist/editor-loader.d.ts

@@ -0,0 +1,9 @@
+export type EditorModule = typeof import('./editor');
+export type RecorderModule = typeof import('./replay/recorder');
+export declare function setEditorBase(_scriptSrc: string): void;
+export declare function loadEditor(): Promise<EditorModule>;
+/** AI-15: the session recorder, loaded only on sampled Pro and Agency visits. */
+export declare function loadRecorder(): Promise<RecorderModule>;
+/** W-20: axe-core, loaded only when a visitor sends an accessibility report. */
+export type ScannerModule = typeof import('./a11y/scan');
+export declare function loadScanner(): Promise<ScannerModule>;

package/dist/editor-loader.embed.d.ts

@@ -0,0 +1,6 @@
+import type { EditorModule, RecorderModule, ScannerModule } from './editor-loader';
+/** Called by embed.ts with the script tag's own src. */
+export declare function setEditorBase(scriptSrc: string): void;
+export declare function loadEditor(): Promise<EditorModule>;
+export declare function loadRecorder(): Promise<RecorderModule>;
+export declare function loadScanner(): Promise<ScannerModule>;

package/dist/fixcheck.d.ts

@@ -0,0 +1,42 @@
+import type { ConsoleEntry } from './capture/console';
+import type { NetworkEntry } from './capture/network';
+import type { RingBuffer } from './capture/ring';
+import type { FixCheck } from './types';
+/**
+ * AI-17 / P-14: after the owner marks a report Fixed, the backend lists its
+ * page path and error signature in the config. On a sampled share of page
+ * views of that path, the widget watches this page view's console errors
+ * and failed requests (from the existing capture) and, if the same
+ * signature shows up, says so once with `POST /fix-check`. Nothing else is
+ * ever sent: no "all clear", no page views, no log contents.
+ *
+ * AI-20 / P-17 reuses this watcher for open reports (path `*`): each sampled
+ * page view where the same error shows up sends `POST /sighting` once.
+ */
+export type FixCheckOptions = {
+    checks: FixCheck[];
+    /** Already the lower of `fixCheckSampleRate` and `samplingRate`. */
+    sampleRate: number;
+    console: RingBuffer<ConsoleEntry>;
+    network: RingBuffer<NetworkEntry>;
+    report: (check: FixCheck) => void;
+    path?: () => string;
+    random?: () => number;
+    now?: () => number;
+    /**
+     * When the first page view's errors count from. Default: the page load,
+     * so errors from before the config arrived are found. A watcher started
+     * again after consent was withdrawn passes now, so nothing is sent twice.
+     */
+    since?: number;
+};
+/** The signature of a single entry, as if it were the report's only one. */
+export declare function consoleSignature(entry: ConsoleEntry): string | null;
+export declare function networkSignature(entry: NetworkEntry): string | null;
+export declare function watchFixChecks(options: FixCheckOptions): {
+    /** Call on every client-side navigation: a new page view. */
+    navigated: () => void;
+    stop: () => void;
+};
+/** `/book` and `/book/` are the same page (known issues use this too). */
+export declare function samePage(a: string, b: string): boolean;

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import { type Breadcrumb } from './capture/breadcrumbs';
+import { type ConsoleEntry } from './capture/console';
+import { type NetworkEntry } from './capture/network';
+import { RingBuffer } from './capture/ring';
+import type { Recorder } from './replay/recorder';
+import { type ReportConsent } from './report';
+import type { PinaxBasket, PinaxConsent, PinaxOptions, PinaxUser, WidgetConfig } from './types';
+import { WidgetUI } from './ui/widget';
+export type { PinaxBasket, PinaxConsent, PinaxOptions, PinaxUser, } from './types';
+type Watcher = {
+    navigated: () => void;
+    stop: () => void;
+};
+type State = {
+    options: PinaxOptions;
+    api: string;
+    /** P-15: where settings (and, with consent, the page-view count) go. */
+    cdn: string | null;
+    root: ShadowRoot;
+    user?: PinaxUser;
+    config?: WidgetConfig;
+    ui?: WidgetUI;
+    console: RingBuffer<ConsoleEntry>;
+    network: RingBuffer<NetworkEntry>;
+    /** AI-11 */
+    breadcrumbs: RingBuffer<Breadcrumb>;
+    /** AI-15: only on sampled Pro and Agency visits, once loaded. */
+    recorder?: Recorder;
+    /** AI-15: the recorder chunk is on its way. */
+    replayStarting: boolean;
+    /** AI-15: drawn once per page view, whenever consent comes. */
+    replaySampled: boolean;
+    /** Visitor consent so far (`consent()`); used only where the site waits. */
+    consent: ReportConsent;
+    /** The button is up: enabled site, allowed domain (W-18, S-15). */
+    running: boolean;
+    /** AI-17 fix checks and AI-20 sightings, while they run. */
+    watchers: {
+        fixChecks?: Watcher;
+        sightings?: Watcher;
+    };
+    /** When consent was last withdrawn: watchers started again count from here. */
+    watchersSince?: number;
+    /** B-16: this page load was counted after consent. */
+    counted: boolean;
+    /** C-10: stops console or network capture when the site has it off. */
+    stopCapture: {
+        console?: () => void;
+        network?: () => void;
+    };
+    /** Run on every client-side navigation (one history watcher for all). */
+    onNavigate: Array<() => void>;
+    cleanups: Array<() => void>;
+    openWhenReady: boolean;
+    alive: boolean;
+};
+/**
+ * Starts the widget: context capture right away (C-04, C-05), then the
+ * button once settings arrive. Safe to call more than once; later calls are
+ * ignored.
+ */
+export declare function init(options: PinaxOptions): void;
+/** Opens the feedback panel from the site's own link or button (S-05). */
+export declare function open(): void;
+/**
+ * Visitor consent from the site's cookie banner: `consent(true)` or
+ * `consent(false)` for everything, or `consent({ diagnostics, replay })`
+ * for only the parts given. Can be called before init(), any number of
+ * times; withdrawing stops what it covers straight away. Only matters where
+ * the page waits for consent (the site's setting or `data-consent="wait"`).
+ */
+export declare function consent(choice: PinaxConsent): void;
+/** Attaches the signed-in visitor to future reports (C-09). Can be called before init(). */
+export declare function identify(user: PinaxUser | null): void;
+/**
+ * AI-21: the visitor's basket total, e.g. `setBasket({ value: 42.5, currency:
+ * 'GBP' })`, or `null` once it's empty. Can be called before init(). Pinax
+ * only sends it alongside a sampled sighting of a known error (P-17).
+ */
+export declare function setBasket(next: PinaxBasket | null): void;
+export declare function cleanBasket(b: unknown): PinaxBasket | undefined;
+/** Removes the widget and stops all capture. Mainly for tests and SPA teardown. */
+export declare function destroy(): void;
+/** @internal */
+export declare function getState(): Readonly<State> | null;

package/dist/known.d.ts

@@ -0,0 +1,27 @@
+import type { ConsoleEntry } from './capture/console';
+import type { NetworkEntry } from './capture/network';
+import type { RingBuffer } from './capture/ring';
+import type { KnownIssue } from './types';
+/** The card lists at most this many. */
+export declare const MAX_KNOWN_SHOWN = 3;
+/**
+ * Known issues: which of the site's public reports this visitor may be
+ * looking at. One matches when one of its `paths` is this page (`/a` and
+ * `/a/` are the same; `*` means nothing special here), or when its error
+ * signature showed up in this page view's console errors or failed requests.
+ * Every page view is watched (no sampling) and nothing is ever sent: the
+ * result is only used to show the card when the panel opens.
+ */
+export declare function watchKnown(options: {
+    known: KnownIssue[];
+    console: RingBuffer<ConsoleEntry>;
+    network: RingBuffer<NetworkEntry>;
+    path?: () => string;
+    now?: () => number;
+}): {
+    matches: () => KnownIssue[];
+    navigated: () => void;
+    stop: () => void;
+};
+/** The issues for this page, in the config's order (newest first), at most 3. */
+export declare function matchKnown(known: KnownIssue[], path: string, seen?: ReadonlySet<string>): KnownIssue[];

package/dist/mount.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates the widget's host element with an (open-mode) Shadow DOM so the
+ * widget's styles never leak into, or inherit from, the host page (W-14).
+ * Open mode keeps it reachable for the editor and tests; it is not a privacy
+ * boundary. Idempotent: a second call returns the existing root.
+ */
+export declare function mountRoot(doc?: Document): ShadowRoot;
+export declare function unmountRoot(doc?: Document): void;

package/dist/navigation.d.ts

@@ -0,0 +1 @@
+export declare function watchNavigation(onChange: () => void, target?: Window): () => void;

package/dist/paths.d.ts

@@ -0,0 +1,4 @@
+/** True when `pathname` matches `pattern` (see the rules above). */
+export declare function pathMatches(pattern: string, pathname: string): boolean;
+/** True when the button should be hidden on `pathname`. */
+export declare function isHiddenPath(patterns: readonly string[] | undefined, pathname: string): boolean;