@setsquare/review-sdk 0.0.1

package/dist/links.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Every URL the SDK is allowed to know about, in one file.
+ *
+ * `boundaries.test.ts` forbids hardcoded URLs everywhere else in the shipped
+ * source and permits them only here. That is deliberately stricter than a blanket
+ * exemption: it means any future URL — a telemetry endpoint, a version check, an
+ * error reporter — has to be added to a file whose entire purpose is to be read
+ * during review, rather than appearing quietly inside a module nobody re-reads.
+ *
+ * None of these is ever REQUESTED. The SDK contains no network client and cannot
+ * fetch anything; these are strings printed for a human to click.
+ */
+/** Printed once per run, in the closing block. Never fetched. */
+export declare const PLATFORM_URL = "https://setsquare.dev";
+/**
+ * Where a rule's remediation guidance lives.
+ *
+ * Currently Deque's own page, taken from axe's `helpUrl` — which makes it an
+ * SDK-computed fact rather than authored content, and keeps the free layer on
+ * the right side of its own boundary. Setsquare's fix-pattern library (P5)
+ * replaces this with our own pages when they exist, and the terminal will still
+ * only ever link: the guidance itself stays on the site, free to read, and
+ * in-context delivery is what the platform sells.
+ */
+export declare function ruleHelpUrl(finding: {
+    helpUrl?: string;
+}): string | undefined;
+/**
+ * The W3C Understanding page for 3.1.5 Reading Level — the spec the
+ * `setsquare-reading-level` heuristic is implemented from, and where a person
+ * deciding the criterion should start. Printed and linked, never fetched.
+ */
+export declare const READING_LEVEL_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/reading-level.html";
+/**
+ * The Understanding pages for the criteria Setsquare's own rule pack
+ * implements — the specs the checks are written FROM (clean-room: axe's rule
+ * source is never opened), and where a person triaging a finding should start.
+ * Printed and linked, never fetched.
+ */
+export declare const TARGET_SIZE_ENHANCED_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html";
+export declare const VISUAL_PRESENTATION_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html";
+export declare const LINK_PURPOSE_LINK_ONLY_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html";
+export declare const TEXT_SPACING_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html";
+export declare const STATUS_MESSAGES_HELP_URL = "https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html";
+//# sourceMappingURL=links.d.ts.map

package/dist/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iEAAiE;AACjE,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,mEAC+B,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,0EAC+B,CAAC;AAC1E,eAAO,MAAM,4BAA4B,yEAC+B,CAAC;AACzE,eAAO,MAAM,+BAA+B,4EAC+B,CAAC;AAC5E,eAAO,MAAM,qBAAqB,kEAC+B,CAAC;AAClE,eAAO,MAAM,wBAAwB,qEAC+B,CAAC"}

package/dist/links.js

@@ -0,0 +1,45 @@
+/**
+ * Every URL the SDK is allowed to know about, in one file.
+ *
+ * `boundaries.test.ts` forbids hardcoded URLs everywhere else in the shipped
+ * source and permits them only here. That is deliberately stricter than a blanket
+ * exemption: it means any future URL — a telemetry endpoint, a version check, an
+ * error reporter — has to be added to a file whose entire purpose is to be read
+ * during review, rather than appearing quietly inside a module nobody re-reads.
+ *
+ * None of these is ever REQUESTED. The SDK contains no network client and cannot
+ * fetch anything; these are strings printed for a human to click.
+ */
+/** Printed once per run, in the closing block. Never fetched. */
+export const PLATFORM_URL = 'https://setsquare.dev';
+/**
+ * Where a rule's remediation guidance lives.
+ *
+ * Currently Deque's own page, taken from axe's `helpUrl` — which makes it an
+ * SDK-computed fact rather than authored content, and keeps the free layer on
+ * the right side of its own boundary. Setsquare's fix-pattern library (P5)
+ * replaces this with our own pages when they exist, and the terminal will still
+ * only ever link: the guidance itself stays on the site, free to read, and
+ * in-context delivery is what the platform sells.
+ */
+export function ruleHelpUrl(finding) {
+    return finding.helpUrl;
+}
+/**
+ * The W3C Understanding page for 3.1.5 Reading Level — the spec the
+ * `setsquare-reading-level` heuristic is implemented from, and where a person
+ * deciding the criterion should start. Printed and linked, never fetched.
+ */
+export const READING_LEVEL_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/reading-level.html';
+/**
+ * The Understanding pages for the criteria Setsquare's own rule pack
+ * implements — the specs the checks are written FROM (clean-room: axe's rule
+ * source is never opened), and where a person triaging a finding should start.
+ * Printed and linked, never fetched.
+ */
+export const TARGET_SIZE_ENHANCED_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html';
+export const VISUAL_PRESENTATION_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html';
+export const LINK_PURPOSE_LINK_ONLY_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html';
+export const TEXT_SPACING_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html';
+export const STATUS_MESSAGES_HELP_URL = 'https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html';
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAA6B;IACvD,OAAO,OAAO,CAAC,OAAO,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,gEAAgE,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GACxC,uEAAuE,CAAC;AAC1E,MAAM,CAAC,MAAM,4BAA4B,GACvC,sEAAsE,CAAC;AACzE,MAAM,CAAC,MAAM,+BAA+B,GAC1C,yEAAyE,CAAC;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAChC,+DAA+D,CAAC;AAClE,MAAM,CAAC,MAAM,wBAAwB,GACnC,kEAAkE,CAAC"}

package/dist/mask.d.ts

@@ -0,0 +1,85 @@
+import type { Locator, Page } from '@playwright/test';
+/**
+ * Masking: deciding what must never be visible in a screenshot.
+ *
+ * Note what this file does NOT do — it takes no screenshots, and the SDK
+ * contains no code that does. That is the free-layer boundary as a structural
+ * property rather than a setting: visual evidence is a platform capability, so
+ * the local path holds no pixels at all, and there is no capture path to
+ * accidentally leave switched on. `boundaries.test.ts` asserts that no shipped
+ * source file so much as names an image format.
+ *
+ * What exists here is the part that has to be right BEFORE any bytes are ever
+ * captured: which regions are covered. Playwright masks at capture time — it
+ * paints over the region before the image exists — so a screenshot taken with
+ * these locators never contains the pixels at all. That is meaningfully
+ * different from blurring afterwards, where the original existed, however
+ * briefly, and may sit in a trace or a temp file.
+ *
+ * The composition is proven against a real page in
+ * `fixtures/specs/anonymous/masking.spec.ts`, which is also the only place in the
+ * repo that takes a screenshot — into memory, never to disk.
+ */
+/**
+ * Selectors masked unless a customer opts out.
+ *
+ * Chosen to be defensible rather than exhaustive, because both errors are real:
+ * masking too little puts a candidate's email in an evidence artifact, and
+ * masking too much produces a screenshot of grey boxes that proves nothing about
+ * accessibility.
+ *
+ * The rule applied: mask fields whose CONTENT is personal by definition, and
+ * leave everything else to configuration. A `<div>` holding a name is
+ * indistinguishable from a `<div>` holding a job title, so it is not guessed at.
+ */
+export declare const DEFAULT_MASK_SELECTORS: readonly ["[data-setsquare-mask]", "input[type=\"password\"]", "input[type=\"email\"]", "input[type=\"tel\"]", "[autocomplete*=\"cc-\"]", "[autocomplete=\"email\"]", "[autocomplete=\"tel\"]", "[autocomplete*=\"name\"]", "[autocomplete=\"street-address\"]", "[autocomplete=\"postal-code\"]", "[autocomplete=\"bday\"]"];
+export interface MaskConfig {
+    /** Extra selectors, composed WITH the defaults rather than replacing them. */
+    mask?: string[];
+    /**
+     * Drop the built-in defaults.
+     *
+     * Available because a customer's page may legitimately use these attributes on
+     * non-personal fields, and being unable to correct us would make the feature
+     * unusable. Turning them off is a deliberate, documented act — which is the
+     * standard the upload defaults are held to as well.
+     */
+    maskDefaults?: boolean;
+}
+/**
+ * The full selector list, defaults first.
+ *
+ * Deduplicated, because a customer repeating a default should not produce two
+ * identical locators and twice the work; ordered deterministically so two runs
+ * of the same configuration mask identically.
+ */
+export declare function maskSelectors(config?: MaskConfig): string[];
+/**
+ * Resolve the selectors to locators for `page.screenshot({ mask })`.
+ *
+ * Deliberately returns locators rather than taking the screenshot itself. The
+ * SDK's job here is to know WHAT to cover; the platform slice that eventually
+ * captures and uploads is what will call this. Keeping the two apart is what lets
+ * the local path be structurally incapable of producing an image rather than
+ * merely configured not to.
+ */
+export declare function maskLocators(page: Page, config?: MaskConfig): Locator[];
+/**
+ * Upload defaults, locked.
+ *
+ * Not a suggestion and not a starting point: these are the values the product's
+ * data-protection posture is built on, and changing any of them is an explicit,
+ * documented act by the customer rather than something that drifts.
+ *
+ * `traces: 'off'` is the strictest of the three and the least negotiable. A
+ * Playwright trace contains full DOM snapshots, network payloads and screenshots
+ * of every step — it is the richest possible source of exactly the data
+ * sanitisation and masking exist to keep out.
+ */
+export declare const UPLOAD_DEFAULTS: {
+    readonly screenshots: "masked-only";
+    readonly traces: "off";
+    readonly htmlSnippets: "strip";
+};
+export type UploadDefaults = typeof UPLOAD_DEFAULTS;
+//# sourceMappingURL=mask.d.ts.map

package/dist/mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.d.ts","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,+TAwBzB,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,UAAe,GAAG,MAAM,EAAE,CAM/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,EAAE,CAE3E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,OAAO,eAAe,CAAC"}

package/dist/mask.js

@@ -0,0 +1,98 @@
+/**
+ * Masking: deciding what must never be visible in a screenshot.
+ *
+ * Note what this file does NOT do — it takes no screenshots, and the SDK
+ * contains no code that does. That is the free-layer boundary as a structural
+ * property rather than a setting: visual evidence is a platform capability, so
+ * the local path holds no pixels at all, and there is no capture path to
+ * accidentally leave switched on. `boundaries.test.ts` asserts that no shipped
+ * source file so much as names an image format.
+ *
+ * What exists here is the part that has to be right BEFORE any bytes are ever
+ * captured: which regions are covered. Playwright masks at capture time — it
+ * paints over the region before the image exists — so a screenshot taken with
+ * these locators never contains the pixels at all. That is meaningfully
+ * different from blurring afterwards, where the original existed, however
+ * briefly, and may sit in a trace or a temp file.
+ *
+ * The composition is proven against a real page in
+ * `fixtures/specs/anonymous/masking.spec.ts`, which is also the only place in the
+ * repo that takes a screenshot — into memory, never to disk.
+ */
+/**
+ * Selectors masked unless a customer opts out.
+ *
+ * Chosen to be defensible rather than exhaustive, because both errors are real:
+ * masking too little puts a candidate's email in an evidence artifact, and
+ * masking too much produces a screenshot of grey boxes that proves nothing about
+ * accessibility.
+ *
+ * The rule applied: mask fields whose CONTENT is personal by definition, and
+ * leave everything else to configuration. A `<div>` holding a name is
+ * indistinguishable from a `<div>` holding a job title, so it is not guessed at.
+ */
+export const DEFAULT_MASK_SELECTORS = [
+    /*
+     * The explicit opt-in, first. A customer who has marked something is telling us
+     * about their own data model, which nothing here can infer.
+     */
+    '[data-setsquare-mask]',
+    // Input types whose content is personal by definition.
+    'input[type="password"]',
+    'input[type="email"]',
+    'input[type="tel"]',
+    /*
+     * Autocomplete tokens — the standard vocabulary browsers already use to
+     * identify personal fields, which makes it the closest thing to a declared
+     * schema for PII that exists on the open web.
+     */
+    '[autocomplete*="cc-"]',
+    '[autocomplete="email"]',
+    '[autocomplete="tel"]',
+    '[autocomplete*="name"]',
+    '[autocomplete="street-address"]',
+    '[autocomplete="postal-code"]',
+    '[autocomplete="bday"]',
+];
+/**
+ * The full selector list, defaults first.
+ *
+ * Deduplicated, because a customer repeating a default should not produce two
+ * identical locators and twice the work; ordered deterministically so two runs
+ * of the same configuration mask identically.
+ */
+export function maskSelectors(config = {}) {
+    const useDefaults = config.maskDefaults ?? true;
+    const selectors = [...(useDefaults ? DEFAULT_MASK_SELECTORS : []), ...(config.mask ?? [])];
+    return [...new Set(selectors.filter((selector) => selector.trim().length > 0))];
+}
+/**
+ * Resolve the selectors to locators for `page.screenshot({ mask })`.
+ *
+ * Deliberately returns locators rather than taking the screenshot itself. The
+ * SDK's job here is to know WHAT to cover; the platform slice that eventually
+ * captures and uploads is what will call this. Keeping the two apart is what lets
+ * the local path be structurally incapable of producing an image rather than
+ * merely configured not to.
+ */
+export function maskLocators(page, config = {}) {
+    return maskSelectors(config).map((selector) => page.locator(selector));
+}
+/**
+ * Upload defaults, locked.
+ *
+ * Not a suggestion and not a starting point: these are the values the product's
+ * data-protection posture is built on, and changing any of them is an explicit,
+ * documented act by the customer rather than something that drifts.
+ *
+ * `traces: 'off'` is the strictest of the three and the least negotiable. A
+ * Playwright trace contains full DOM snapshots, network payloads and screenshots
+ * of every step — it is the richest possible source of exactly the data
+ * sanitisation and masking exist to keep out.
+ */
+export const UPLOAD_DEFAULTS = {
+    screenshots: 'masked-only',
+    traces: 'off',
+    htmlSnippets: 'strip',
+};
+//# sourceMappingURL=mask.js.map

package/dist/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC;;;OAGG;IACH,uBAAuB;IAEvB,uDAAuD;IACvD,wBAAwB;IACxB,qBAAqB;IACrB,mBAAmB;IAEnB;;;;OAIG;IACH,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,wBAAwB;IACxB,iCAAiC;IACjC,8BAA8B;IAC9B,uBAAuB;CACf,CAAC;AAgBX;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,SAAqB,EAAE;IACnD,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC;IAEhD,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IAE3F,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,IAAU,EAAE,SAAqB,EAAE;IAC9D,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,aAAa;IAC1B,MAAM,EAAE,KAAK;IACb,YAAY,EAAE,OAAO;CACb,CAAC"}

package/dist/observe.d.ts

@@ -0,0 +1,51 @@
+import type { Page } from '@playwright/test';
+import type { PageRuntime, PageRuntimeEvent, PageRuntimeKind } from '@setsquare/schema';
+/**
+ * A bounded per-page accumulator.
+ *
+ * Deliberately not a class with a `toJSON`: the reporter never sees this object,
+ * only the plain `PageRuntime` that `snapshot()` returns.
+ */
+export declare class PageRuntimeAccumulator {
+    private readonly startedAt;
+    private readonly counts;
+    private readonly distinct;
+    private omitted;
+    constructor(startedAt: number);
+    /**
+     * Record one event.
+     *
+     * `key` is what makes two events "the same" for exemplar purposes — the same
+     * error thrown a thousand times is one thing that is wrong, not a thousand.
+     */
+    add(kind: PageRuntimeKind, key: string, event: () => Omit<PageRuntimeEvent, 'kind' | 'atMs'>): void;
+    /**
+     * The wire shape. **Always a block, never `undefined`.**
+     *
+     * A clean page returns `{ observed: [...6 kinds], counts: {} }`, and that is
+     * the entire point rather than wasted bytes: it is the difference between "we
+     * listened and saw none" and "we did not look". The second is expressed by the
+     * scan carrying no `runtime` at all — which happens when this is not the first
+     * scan of a page load, or when the envelope predates the capability.
+     *
+     * A bare `consoleErrors: 0` could express neither, which is why no such field
+     * exists. Same rule `perf.ts` follows for CLS on engines that cannot measure it.
+     */
+    snapshot(): PageRuntime;
+}
+/**
+ * This page's runtime block, or `undefined` if the page was never observed.
+ *
+ * Callers gate this the way `perf` is gated — first scan of a `visitRef` only —
+ * because these are facts about a page LOAD, not about a scan. Scanning one page
+ * in four states must not report its console errors four times.
+ */
+export declare function pageRuntime(page: Page): PageRuntime | undefined;
+/**
+ * Attach the runtime listeners to one page.
+ *
+ * Never throws: an engine that refuses a listener must cost the customer nothing,
+ * and partial evidence beats none provided we do not pretend it is complete.
+ */
+export declare function observePageRuntime(page: Page, startedAt: number): void;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,IAAI,EAAqB,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAmFxF;;;;;GAKG;AACH,qBAAa,sBAAsB;IAKrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,OAAO,CAAK;gBAES,SAAS,EAAE,MAAM;IAE9C;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAAC;IAmB5F;;;;;;;;;;;OAWG;IACH,QAAQ,IAAI,WAAW;CAWxB;AAkCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,SAAS,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CA8DtE"}

package/dist/observe.js

@@ -0,0 +1,233 @@
+import { MAX_DISTINCT_RUNTIME_EVENTS, MAX_RUNTIME_EXEMPLARS, MAX_RUNTIME_MESSAGE_LENGTH, } from '@setsquare/schema/limits';
+import { capLength, stripHostileCharacters, toUrlPattern } from './sanitise.js';
+/**
+ * What the page itself did while we were on it.
+ *
+ * The SDK already holds the richest object in the run — a live `BrowserContext` —
+ * and until now read one event off it. Everything here is on that object, costs
+ * approximately nothing, and is aggregated nowhere in Playwright's own report:
+ * a 500 on a background XHR during fourteen passing tests fails no assertion and
+ * appears in no artefact.
+ *
+ * ---------------------------------------------------------------------------
+ * THIS CODE RUNS IN A CUSTOMER'S TEST PROCESS, ON EVERY PAGE. Three constraints
+ * follow, and none of them is negotiable:
+ *
+ * 1. `response` fires for EVERY response. A media-heavy page is 300–800 of them,
+ *    times the tests, times the engines — six figures of events in a run. So the
+ *    handler is fully synchronous, reads only synchronous getters, and returns on
+ *    its first line for the overwhelmingly common case (`status < 400`), which
+ *    means the common path allocates nothing at all.
+ *
+ * 2. It must NEVER read a response body. `response.text()` / `.body()` / `.json()`
+ *    buffer the payload and can deadlock a page whose request is still streaming
+ *    — turning an observer into the cause of a customer's timeout. A grep
+ *    assertion in `observe.test.ts` enforces this, because the failure would be
+ *    intermittent and would be blamed on their app.
+ *
+ * 3. Memory is counters plus a bounded exemplar set, never a log. A page throwing
+ *    inside `requestAnimationFrame` emits without limit for the length of the
+ *    test; uncapped, the map grows with it. Worst case at the current caps is
+ *    roughly 15 KB per page (50 distinct keys, 20 exemplars at the message cap).
+ * ---------------------------------------------------------------------------
+ *
+ * The listeners attach per page, from the context fixture's existing `observe`,
+ * which keeps the measured `context`-over-`page` fixture win intact: a test that
+ * never opens a browser opens no page and therefore pays nothing.
+ *
+ * Sanitisation happens here rather than in the reporter, for the reason
+ * `contract.ts` gives — an attachment is also written into Playwright's own HTML
+ * report and trace, so a hostile console message must be bounded before it leaves
+ * the worker, not after.
+ */
+/**
+ * Which categories we attach listeners for.
+ *
+ * Playwright normalises `console`, `pageerror`, `requestfailed` and `response`
+ * across all three engines at the API level, so the listeners themselves are
+ * portable. The CONTENT is not, as the cross-engine lane
+ * (`fixtures/playwright.engines.config.ts`) measured: on the same page Chromium
+ * and WebKit report 123 console errors and Firefox 121, because the first two also
+ * log a failed-resource error and Firefox does not. So a count is a fact about one
+ * engine's console and must never be summed or compared across them.
+ *
+ * `request.failure()?.errorText` is likewise engine-specific
+ * (`net::ERR_BLOCKED_BY_CSP` in Chromium, other wording in Gecko and WebKit).
+ * Hence the rule this module follows and the schema documents: carry `errorText`
+ * verbatim, never classify a cause from message text. A `blocked-by-csp`
+ * category derived from prose would read as computed while being guessed.
+ *
+ * Worth recording honestly: `pageerror` message wording happened to AGREE on all
+ * three for the fixture's two errors. That is not a guarantee — V8, SpiderMonkey
+ * and JSC merely phrase those particular two the same way — and it is why nothing
+ * is parsed out of a message even though it would have worked on that fixture.
+ */
+const OBSERVED_KINDS = [
+    'console-error',
+    'console-warning',
+    'page-error',
+    'request-failed',
+    'response-4xx',
+    'response-5xx',
+];
+/**
+ * A bounded per-page accumulator.
+ *
+ * Deliberately not a class with a `toJSON`: the reporter never sees this object,
+ * only the plain `PageRuntime` that `snapshot()` returns.
+ */
+export class PageRuntimeAccumulator {
+    startedAt;
+    counts = {};
+    distinct = new Map();
+    omitted = 0;
+    constructor(startedAt) {
+        this.startedAt = startedAt;
+    }
+    /**
+     * Record one event.
+     *
+     * `key` is what makes two events "the same" for exemplar purposes — the same
+     * error thrown a thousand times is one thing that is wrong, not a thousand.
+     */
+    add(kind, key, event) {
+        this.counts[kind] = (this.counts[kind] ?? 0) + 1;
+        if (this.distinct.has(key))
+            return;
+        if (this.distinct.size >= MAX_DISTINCT_RUNTIME_EVENTS) {
+            this.omitted += 1;
+            return;
+        }
+        // The event body is built lazily, so a repeat of something already seen — the
+        // common case on a noisy page — costs one map lookup and an integer bump.
+        this.distinct.set(key, {
+            kind,
+            ...event(),
+            atMs: Math.max(0, Date.now() - this.startedAt),
+        });
+    }
+    /**
+     * The wire shape. **Always a block, never `undefined`.**
+     *
+     * A clean page returns `{ observed: [...6 kinds], counts: {} }`, and that is
+     * the entire point rather than wasted bytes: it is the difference between "we
+     * listened and saw none" and "we did not look". The second is expressed by the
+     * scan carrying no `runtime` at all — which happens when this is not the first
+     * scan of a page load, or when the envelope predates the capability.
+     *
+     * A bare `consoleErrors: 0` could express neither, which is why no such field
+     * exists. Same rule `perf.ts` follows for CLS on engines that cannot measure it.
+     */
+    snapshot() {
+        return {
+            observed: [...OBSERVED_KINDS],
+            counts: { ...this.counts },
+            distinct: this.distinct.size,
+            omitted: this.omitted,
+            // First-seen rather than most-frequent: most-frequent would require keeping
+            // the full frequency map, which is the bound this class exists to hold.
+            exemplars: [...this.distinct.values()].slice(0, MAX_RUNTIME_EXEMPLARS),
+        };
+    }
+}
+const message = (value) => capLength(stripHostileCharacters(value), MAX_RUNTIME_MESSAGE_LENGTH);
+/*
+ * Page-keyed, and held on a REGISTERED SYMBOL rather than in a module-level
+ * variable.
+ *
+ * This is the one piece of state that genuinely crosses module copies: the
+ * context fixture writes it and the two scan paths read it. A plain
+ * module-scoped `WeakMap` looks equivalent and is not — a package can be
+ * resolved twice in one process (ESM and CJS, or a source import beside a
+ * package import in a monorepo), and each copy would carry its own empty map.
+ * `runtime.ts` records the same hazard for the rule policy.
+ *
+ * Found the hard way: on the SDK's own fixture suite, auto-scans (reached through
+ * the source import) carried runtime evidence and explicit `setsquare.scan()`
+ * calls (reached through the package import) silently carried none. Nothing
+ * failed — the block was simply absent, which is indistinguishable from a clean
+ * page unless you know to look. Exactly the class of quiet wrongness this feature
+ * exists to expose in other people's tools.
+ */
+const ACCUMULATORS = Symbol.for('setsquare.playwright.page-runtime');
+function accumulatorMap() {
+    const store = globalThis;
+    const existing = store[ACCUMULATORS];
+    if (existing)
+        return existing;
+    const created = new WeakMap();
+    store[ACCUMULATORS] = created;
+    return created;
+}
+/**
+ * This page's runtime block, or `undefined` if the page was never observed.
+ *
+ * Callers gate this the way `perf` is gated — first scan of a `visitRef` only —
+ * because these are facts about a page LOAD, not about a scan. Scanning one page
+ * in four states must not report its console errors four times.
+ */
+export function pageRuntime(page) {
+    return accumulatorMap().get(page)?.snapshot();
+}
+/**
+ * Attach the runtime listeners to one page.
+ *
+ * Never throws: an engine that refuses a listener must cost the customer nothing,
+ * and partial evidence beats none provided we do not pretend it is complete.
+ */
+export function observePageRuntime(page, startedAt) {
+    const accumulator = new PageRuntimeAccumulator(startedAt);
+    accumulatorMap().set(page, accumulator);
+    try {
+        page.on('console', (entry) => {
+            // First line, so a page logging chattily at `log`/`info`/`debug` — which is
+            // most pages — allocates nothing.
+            const type = entry.type();
+            if (type !== 'error' && type !== 'warning')
+                return;
+            const kind = type === 'error' ? 'console-error' : 'console-warning';
+            const text = message(entry.text());
+            // Exemplar keys join on U+0000 throughout this file: it is banned from every
+            // string the contract accepts, so a message containing the separator cannot
+            // collapse two distinct events into one. Same convention as the dedupe key.
+            accumulator.add(kind, `${kind}\u0000${text}`, () => ({ message: text }));
+        });
+        page.on('pageerror', (error) => {
+            // Carry the message, never a parsed class name: stack and wording differ
+            // per engine, so a taxonomy built from them would be engine-dependent while
+            // looking canonical.
+            const text = message(error.message || String(error));
+            accumulator.add('page-error', `page-error\u0000${text}`, () => ({ message: text }));
+        });
+        page.on('requestfailed', (request) => {
+            const pattern = toUrlPattern(request.url()).pattern;
+            const errorText = request.failure()?.errorText;
+            const detail = errorText === undefined ? undefined : capLength(stripHostileCharacters(errorText), 128);
+            accumulator.add('request-failed', `request-failed\u0000${pattern}\u0000${detail ?? ''}`, () => ({ urlPattern: pattern, ...(detail === undefined ? {} : { errorText: detail }) }));
+        });
+        page.on('response', (response) => {
+            /*
+             * The hot path. Every response on every page reaches this line, so the
+             * cheap check comes first and the common case does no work beyond it.
+             *
+             * Only synchronous getters below. Reading a body here would buffer it and
+             * can deadlock a streaming request — see the header note; there is a test
+             * that greps this file to keep it that way.
+             */
+            const status = response.status();
+            if (status < 400)
+                return;
+            const kind = status >= 500 ? 'response-5xx' : 'response-4xx';
+            const pattern = toUrlPattern(response.url()).pattern;
+            accumulator.add(kind, `${kind}\u0000${status}\u0000${pattern}`, () => ({
+                urlPattern: pattern,
+                status,
+            }));
+        });
+    }
+    catch {
+        // A context or engine that refuses a listener yields no runtime evidence for
+        // that page. It must never cost the customer a test.
+    }
+}
+//# sourceMappingURL=observe.js.map

package/dist/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"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"}