@setsquare/review-sdk 0.0.1

package/dist/shots.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Screenshots, indexed rather than taken.
+ *
+ * This module is the whole reason the visual report does not breach decision 4.
+ * Setsquare holds no pixels: it takes no screenshot, writes no image, and
+ * copies nothing. What it does is read the image attachments Playwright ALREADY
+ * wrote — because the customer set `screenshot: 'on'`, called
+ * `toHaveScreenshot()`, or attached one themselves — and record where they are.
+ * The contact sheet then links to those files where they lie.
+ *
+ * That distinction is not pedantry. "The local path holds no pixels" is what
+ * makes PII-safety structural rather than best-effort, and a helper that
+ * screenshotted on the customer's behalf would move the responsibility for an
+ * unmasked capture from their config to our code. Indexing leaves it exactly
+ * where it already was: with the person who turned Playwright's screenshots on.
+ *
+ * It also means the SDK cannot compare anything. Where a comparison appears in
+ * the report, Playwright's own `toHaveScreenshot()` made it — we found the
+ * expected/actual/diff trio it attached and put the three side by side. There is
+ * no baseline here, no history, and no verdict: a person scans and decides.
+ */
+/**
+ * Which part of a comparison an image is, or `shot` for a standalone capture.
+ *
+ * Read from the attachment name because that is where Playwright puts it:
+ * `toHaveScreenshot()` attaches `<base>-expected`, `-actual`, `-diff` and
+ * (on a retry that changed) `-previous`, all sharing one base name.
+ */
+export type ShotRole = 'expected' | 'previous' | 'actual' | 'diff' | 'shot';
+export interface Shot {
+    /** The attachment name, exactly as Playwright reported it. */
+    name: string;
+    /** Name with the role suffix and extension removed; the trio's shared key. */
+    base: string;
+    role: ShotRole;
+    contentType: string;
+    /** Absolute path, on the machine that captured it. Never read, only linked. */
+    path: string;
+}
+/**
+ * The attachment shape, structurally typed.
+ *
+ * Playwright's own `TestResult['attachments']` element, restated as the three
+ * fields this module reads. Typed structurally so the classifier can be tested
+ * without constructing a Playwright test result, which is a large object with a
+ * lot of it irrelevant here.
+ */
+export interface ImageAttachment {
+    name: string;
+    contentType: string;
+    path?: string | undefined;
+    body?: Buffer | undefined;
+}
+export interface CollectShotsResult {
+    shots: Shot[];
+    /** Image attachments that exist only in memory, and so cannot be linked to. */
+    inMemory: number;
+}
+/**
+ * Pull the image attachments out of one test result.
+ *
+ * Two cases are deliberately not equivalent. An attachment with a `path` is a
+ * file on disk we can link to. An attachment with only a `body` is an image
+ * Playwright is holding in memory — `testInfo.attach(name, { body })` never
+ * writes it — and putting it in the report would mean writing the bytes
+ * ourselves, which is the one thing this module exists not to do. Those are
+ * COUNTED and reported as a warning, because an image the reader cannot see
+ * must not silently look like an image that was never taken.
+ *
+ * Selection is by `contentType` rather than by file extension. Playwright always
+ * sets it for a screenshot, and reading the type is both more correct than
+ * guessing from a name and the reason this file names no image format at all.
+ */
+export declare function collectShots(attachments: readonly ImageAttachment[]): CollectShotsResult;
+/** One image, or one comparison's images, as the report renders them together. */
+export interface ShotGroup {
+    base: string;
+    /** True when Playwright attached more than one role under this base name. */
+    comparison: boolean;
+    shots: Shot[];
+}
+/**
+ * Group a test's shots into what the report shows as a single unit.
+ *
+ * A `toHaveScreenshot()` failure attaches three or four images that only mean
+ * anything together, so they are grouped by their shared base name and ordered
+ * expected → previous → actual → diff. Everything else is its own group, in the
+ * order it was attached, which is the order the test took them in — the closest
+ * thing the report has to a walkthrough of the flow.
+ */
+export declare function groupShots(shots: readonly Shot[]): ShotGroup[];
+/**
+ * Drop shots whose file is no longer where the attachment said it was.
+ *
+ * Two ordinary situations produce them, and both would otherwise fill a
+ * QA-facing page with broken image icons — which is the fastest way to make
+ * someone stop trusting a report. A merged run group can hold parts captured on
+ * other machines, whose paths mean nothing here. And a suite that cleans its
+ * output directory between the run and the reading leaves the paths dangling.
+ *
+ * Missing shots are COUNTED for the caller to warn about, never quietly
+ * dropped: "the report shows nine of eleven captures" is a fact the reader needs
+ * in order to know they are not looking at everything.
+ */
+export declare function reachableShots(shots: readonly Shot[]): {
+    shots: Shot[];
+    missing: number;
+};
+//# sourceMappingURL=shots.d.ts.map

package/dist/shots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shots.d.ts","sourceRoot":"","sources":["../src/shots.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5E,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;CACd;AAcD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAkBD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,kBAAkB,CAuBxF;AAED,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,EAAE,CAiB9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUzF"}

package/dist/shots.js

@@ -0,0 +1,113 @@
+import { existsSync } from 'node:fs';
+/** Fixed so a comparison always reads left-to-right in the same order. */
+const ROLE_ORDER = {
+    expected: 0,
+    previous: 1,
+    actual: 2,
+    diff: 3,
+    shot: 4,
+};
+/** The suffixes Playwright's snapshot matchers append, longest first. */
+const ROLE_SUFFIXES = ['expected', 'previous', 'actual', 'diff'];
+/** Extension stripped without ever naming an image format. */
+function withoutExtension(name) {
+    return name.replace(/\.[A-Za-z0-9]{1,5}$/, '');
+}
+function classify(name) {
+    const stem = withoutExtension(name);
+    for (const role of ROLE_SUFFIXES) {
+        const suffix = `-${role}`;
+        if (stem.endsWith(suffix))
+            return { base: stem.slice(0, -suffix.length), role };
+    }
+    return { base: stem, role: 'shot' };
+}
+/**
+ * Pull the image attachments out of one test result.
+ *
+ * Two cases are deliberately not equivalent. An attachment with a `path` is a
+ * file on disk we can link to. An attachment with only a `body` is an image
+ * Playwright is holding in memory — `testInfo.attach(name, { body })` never
+ * writes it — and putting it in the report would mean writing the bytes
+ * ourselves, which is the one thing this module exists not to do. Those are
+ * COUNTED and reported as a warning, because an image the reader cannot see
+ * must not silently look like an image that was never taken.
+ *
+ * Selection is by `contentType` rather than by file extension. Playwright always
+ * sets it for a screenshot, and reading the type is both more correct than
+ * guessing from a name and the reason this file names no image format at all.
+ */
+export function collectShots(attachments) {
+    const shots = [];
+    let inMemory = 0;
+    for (const attachment of attachments) {
+        if (!attachment.contentType?.startsWith('image/'))
+            continue;
+        if (!attachment.path) {
+            if (attachment.body)
+                inMemory += 1;
+            continue;
+        }
+        const { base, role } = classify(attachment.name);
+        shots.push({
+            name: attachment.name,
+            base,
+            role,
+            contentType: attachment.contentType,
+            path: attachment.path,
+        });
+    }
+    return { shots, inMemory };
+}
+/**
+ * Group a test's shots into what the report shows as a single unit.
+ *
+ * A `toHaveScreenshot()` failure attaches three or four images that only mean
+ * anything together, so they are grouped by their shared base name and ordered
+ * expected → previous → actual → diff. Everything else is its own group, in the
+ * order it was attached, which is the order the test took them in — the closest
+ * thing the report has to a walkthrough of the flow.
+ */
+export function groupShots(shots) {
+    const groups = new Map();
+    for (const shot of shots) {
+        const existing = groups.get(shot.base);
+        if (existing)
+            existing.push(shot);
+        else
+            groups.set(shot.base, [shot]);
+    }
+    return [...groups].map(([base, members]) => {
+        const roles = new Set(members.map((shot) => shot.role));
+        return {
+            base,
+            comparison: roles.size > 1 || !roles.has('shot'),
+            shots: [...members].sort((a, b) => ROLE_ORDER[a.role] - ROLE_ORDER[b.role]),
+        };
+    });
+}
+/**
+ * Drop shots whose file is no longer where the attachment said it was.
+ *
+ * Two ordinary situations produce them, and both would otherwise fill a
+ * QA-facing page with broken image icons — which is the fastest way to make
+ * someone stop trusting a report. A merged run group can hold parts captured on
+ * other machines, whose paths mean nothing here. And a suite that cleans its
+ * output directory between the run and the reading leaves the paths dangling.
+ *
+ * Missing shots are COUNTED for the caller to warn about, never quietly
+ * dropped: "the report shows nine of eleven captures" is a fact the reader needs
+ * in order to know they are not looking at everything.
+ */
+export function reachableShots(shots) {
+    const reachable = [];
+    let missing = 0;
+    for (const shot of shots) {
+        if (existsSync(shot.path))
+            reachable.push(shot);
+        else
+            missing += 1;
+    }
+    return { shots: reachable, missing };
+}
+//# sourceMappingURL=shots.js.map

package/dist/shots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shots.js","sourceRoot":"","sources":["../src/shots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AA4CrC,0EAA0E;AAC1E,MAAM,UAAU,GAA6B;IAC3C,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,yEAAyE;AACzE,MAAM,aAAa,GAAwB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAiBtF,8DAA8D;AAC9D,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;IAClF,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAQD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,WAAuC;IAClE,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,QAAQ,CAAC;YAAE,SAAS;QAE5D,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YACrB,IAAI,UAAU,CAAC,IAAI;gBAAE,QAAQ,IAAI,CAAC,CAAC;YACnC,SAAS;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,IAAI;YACJ,IAAI;YACJ,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,IAAI,EAAE,UAAU,CAAC,IAAI;SACtB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7B,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACxD,OAAO;YACL,IAAI;YACJ,UAAU,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;YAChD,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC5E,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAAsB;IACnD,MAAM,SAAS,GAAW,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC3C,OAAO,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC"}

package/dist/style.d.ts

@@ -0,0 +1,47 @@
+export interface Style {
+    bold(value: string): string;
+    dim(value: string): string;
+    /** For the one or two figures a line exists to deliver. */
+    figure(value: string): string;
+    heading(value: string): string;
+    /** The wordmark, and nothing else. */
+    accent(value: string): string;
+    on: boolean;
+}
+export declare function createStyle(env?: NodeJS.ProcessEnv, isTTY?: boolean): Style;
+/**
+ * A number in a fixed right-aligned gutter, with its label after it.
+ *
+ * This is the whole layout idea. Putting every figure in the same column, ahead
+ * of its prose, lets a reader scan one narrow strip down the left and take in the
+ * shape of the report without reading a word of it. It degrades perfectly to
+ * plain text, greps cleanly, and survives being pasted into a narrow Slack window
+ * — which a bordered table does not, and which is the main thing that happens to
+ * this output.
+ */
+export declare function figureLine(style: Style, value: string | number, label: string, gutter?: number): string;
+/**
+ * Soft-wrap a long value under the gutter, on word boundaries.
+ *
+ * Wrapping rather than truncating, for the reason the run summary learned the
+ * hard way: a truncated line cuts off the useful half. A repository with five
+ * Playwright configs has a config list longer than any terminal, and the fifth
+ * name matters as much as the first.
+ */
+export declare function continuationLines(style: Style, value: string, width?: number, gutter?: number): string[];
+/** A section heading. Capitals, so it still reads as a heading with colour stripped. */
+export declare function heading(style: Style, text: string): string;
+/**
+ * A heading followed by figure rows and their notes.
+ *
+ * The one repeated shape in the run summary, extracted because P1b adds five more
+ * sections of exactly this form and five hand-rolled copies would drift in
+ * spacing. Fifteen lines rather than a section framework: the existing sections
+ * keep their bespoke layouts, and nothing here retrofits them.
+ */
+export declare function figureBlock(style: Style, title: string, rows: readonly {
+    value: number | string;
+    label: string;
+    notes?: string[];
+}[], notes?: readonly string[], width?: number): string[];
+//# sourceMappingURL=style.d.ts.map

package/dist/style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../src/style.ts"],"names":[],"mappings":"AAkDA,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,sCAAsC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAgB,WAAW,CACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,KAAK,GAAE,OAAuC,GAC7C,KAAK,CAkCP;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,KAAK,EAAE,MAAM,EACb,MAAM,SAAI,GACT,MAAM,CASR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,MAAM,EAAE,CAkB/F;AAED,wFAAwF;AACxF,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,EAC5E,KAAK,GAAE,SAAS,MAAM,EAAO,EAC7B,KAAK,SAAK,GACT,MAAM,EAAE,CAcV"}

package/dist/style.js

@@ -0,0 +1,154 @@
+/*
+ * DUPLICATED FROM `packages/review-cli/src/style.ts`, deliberately, and the reason is
+ * structural rather than laziness.
+ *
+ * Decision 9 (2026-08-17) makes the CLI unable to load into a customer's test
+ * process — that is the whole point of the two-package split, and it is enforced
+ * by there being no import path rather than by a convention anybody has to
+ * remember. The SDK does declare `@setsquare/review-cli` as a dependency, but only so
+ * one install links the `setsquare` binary; importing CLI code from the reporter would
+ * pull the audit, its parser and its adapters into the import graph of every test
+ * run, which is exactly what the split exists to prevent.
+ *
+ * So sixty zero-dependency lines are copied instead. The alternative — a third
+ * published package for a string-wrapping helper — costs more to sign, publish
+ * and review each release than this costs to keep in step, and the two are held
+ * in step by the assertion that matters being made in both suites: strip the
+ * escapes and the output is unchanged.
+ */
+/**
+ * The small amount of terminal styling this product allows itself.
+ *
+ * The governing rule predates this file and does not bend: **colour is
+ * decoration, never information.** Every line must carry its full meaning in
+ * plain text, because we sell accessibility and because CI logs, pipes and pasted
+ * output all lose colour. Nothing here may be the only thing telling a reader
+ * that something failed.
+ *
+ * What styling IS for is hierarchy — making the number a person came for land
+ * before the sentence explaining it. That is a real problem rather than a vanity
+ * one: a well-structured report where every line carries equal weight reads as a
+ * wall, and the reader ends up doing the tool's job of working out what matters.
+ *
+ * Detection follows the informal standard rather than our preference: an explicit
+ * NO_COLOR of any value wins over everything, then FORCE_COLOR, then whether we
+ * are actually talking to a terminal. CI is treated as no-colour deliberately —
+ * build logs are read as text far more often than they are watched live.
+ *
+ * Escapes are written as escape SEQUENCES rather than literal control bytes. A
+ * literal escape makes the file binary to grep and awkward to diff, and a styling
+ * module is precisely the file nobody should have to fight to read.
+ */
+function enabled(env, isTTY) {
+    if (env['NO_COLOR'] !== undefined)
+        return false;
+    if (env['FORCE_COLOR'] !== undefined)
+        return env['FORCE_COLOR'] !== '0';
+    if (env['CI'] !== undefined)
+        return false;
+    return isTTY;
+}
+export function createStyle(env = process.env, isTTY = Boolean(process.stdout.isTTY)) {
+    const on = enabled(env, isTTY);
+    const wrap = (code) => (value) => on ? `\u001B[${code}m${value}\u001B[0m` : value;
+    return {
+        on,
+        bold: wrap('1'),
+        dim: wrap('2'),
+        /*
+         * Figures stay BOLD, deliberately, while headings get hue.
+         *
+         * The numbers are the content — they must read as figures on a monochrome
+         * terminal, in a pipe, and to anyone whose colour perception differs from
+         * ours, so they lean on weight, which survives all three. Hue is spent on
+         * structure instead: headings and the wordmark, where losing it costs a
+         * reader nothing but noticing it helps them find their place.
+         */
+        figure: wrap('1'),
+        /*
+         * The basic 16-colour codes rather than 256-colour or truecolour, and that is
+         * an accessibility decision rather than a compatibility one.
+         *
+         * Codes 30-37 are remapped by the terminal to the user's OWN theme, so cyan on
+         * a light Solarized profile and cyan on a dark one are both legible because
+         * the person chose them. A hard-coded #7c3aed looks right in our terminal and
+         * can be genuinely unreadable in someone else's — and picking an unreadable
+         * colour would be a poor advertisement for an accessibility company.
+         */
+        heading: wrap('1;36'),
+        // Bold folded in, so callers never nest two wrappers and emit a double reset.
+        accent: wrap('1;35'),
+    };
+}
+/**
+ * A number in a fixed right-aligned gutter, with its label after it.
+ *
+ * This is the whole layout idea. Putting every figure in the same column, ahead
+ * of its prose, lets a reader scan one narrow strip down the left and take in the
+ * shape of the report without reading a word of it. It degrades perfectly to
+ * plain text, greps cleanly, and survives being pasted into a narrow Slack window
+ * — which a bordered table does not, and which is the main thing that happens to
+ * this output.
+ */
+export function figureLine(style, value, label, gutter = 7) {
+    const shown = typeof value === 'number' ? value.toLocaleString('en-GB') : value;
+    // An empty gutter is a continuation line, not a figure. Styling it emits escape
+    // codes around nothing, which is invisible on screen and litters any log that
+    // keeps them.
+    if (shown === '')
+        return `  ${' '.repeat(gutter)}  ${label}`;
+    return `  ${style.figure(String(shown).padStart(gutter))}  ${label}`;
+}
+/**
+ * Soft-wrap a long value under the gutter, on word boundaries.
+ *
+ * Wrapping rather than truncating, for the reason the run summary learned the
+ * hard way: a truncated line cuts off the useful half. A repository with five
+ * Playwright configs has a config list longer than any terminal, and the fifth
+ * name matters as much as the first.
+ */
+export function continuationLines(style, value, width = 80, gutter = 7) {
+    const indent = ' '.repeat(gutter + 4);
+    const room = Math.max(24, width - indent.length);
+    const lines = [];
+    let current = '';
+    for (const word of value.split(' ')) {
+        if (current !== '' && `${current} ${word}`.length > room) {
+            lines.push(`${indent}${style.dim(current)}`);
+            current = word;
+        }
+        else {
+            current = current === '' ? word : `${current} ${word}`;
+        }
+    }
+    if (current !== '')
+        lines.push(`${indent}${style.dim(current)}`);
+    return lines;
+}
+/** A section heading. Capitals, so it still reads as a heading with colour stripped. */
+export function heading(style, text) {
+    return `  ${style.heading(text.toUpperCase())}`;
+}
+/**
+ * A heading followed by figure rows and their notes.
+ *
+ * The one repeated shape in the run summary, extracted because P1b adds five more
+ * sections of exactly this form and five hand-rolled copies would drift in
+ * spacing. Fifteen lines rather than a section framework: the existing sections
+ * keep their bespoke layouts, and nothing here retrofits them.
+ */
+export function figureBlock(style, title, rows, notes = [], width = 80) {
+    if (rows.length === 0 && notes.length === 0)
+        return [];
+    const lines = [heading(style, title)];
+    for (const row of rows) {
+        lines.push(figureLine(style, row.value, row.label));
+        for (const note of row.notes ?? [])
+            lines.push(...continuationLines(style, note, width));
+    }
+    for (const note of notes)
+        lines.push(...continuationLines(style, note, width));
+    lines.push('');
+    return lines;
+}
+//# sourceMappingURL=style.js.map

package/dist/style.js.map

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

package/dist/suite.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Reductions over Playwright's own `TestResult`, which the reporter used to drop.
+ *
+ * `onTestEnd` read six fields and discarded the rest. What was on the object:
+ * `steps` (a tree, with timings), `errors`, `workerIndex`, `annotations`. From
+ * that, with no new instrumentation, come three things nothing else in the run
+ * can say:
+ *
+ *   - where the suite's wall clock actually goes, down to the step
+ *   - which worker held the run open, which is the commonest cheap CI win and is
+ *     invisible in Playwright's own HTML report
+ *   - why a test failed, so `run.json` can be triaged by whoever it is handed to
+ *     rather than only by whoever watched it happen
+ *
+ * Kept out of `reporter.ts` because these are pure functions over plain data and
+ * deserve to be tested as such. The reporter's job is to call them.
+ *
+ * NOT here, and never: `result.stdout`. It is arbitrary customer application and
+ * test log output — the highest-PII surface on the object — and no cap makes it
+ * safe to carry. A grep assertion in `observe.test.ts` keeps it that way.
+ */
+/** The subset of Playwright's `TestStep` this module needs. Structural, so a literal works in tests. */
+export interface StepLike {
+    title: string;
+    category: string;
+    duration: number;
+    error?: unknown;
+    steps?: StepLike[];
+}
+export interface SlowStep {
+    title: string;
+    category: string;
+    durationMs: number;
+}
+export interface TestFailureFacts {
+    errorClass?: string;
+    message?: string;
+    step?: string;
+}
+export declare function errorClassOf(message: string): string | undefined;
+/**
+ * Collapse a message to one line and cap it.
+ *
+ * A Playwright error message is natively multi-line — assertion diff, call log,
+ * code frame — and a newline is a C0 control, which the contract's character
+ * constraint bans. Collapsing rather than permitting newlines is a deliberate
+ * contract decision recorded in `ingest.ts`: one sanitisation rule, not two that
+ * can drift. The repro command is how someone gets the readable original.
+ */
+export declare function collapseMessage(value: string): string;
+/**
+ * The deepest failing step's title.
+ *
+ * Deepest, not first: Playwright marks every ancestor of a failure as failed too,
+ * so the outermost failing step is usually `Before Hooks` or the test body — true,
+ * and useless. The innermost one is the actual operation that broke.
+ */
+export declare function deepestFailingStep(steps: readonly StepLike[] | undefined): string | undefined;
+/**
+ * Why this test failed, from the error list and the step tree.
+ *
+ * Returns `undefined` for a test that did not fail, and for a failed test whose
+ * result carried neither an error nor an identifiable failing step — because
+ * `{}` would imply we looked and found a failure with no properties, which is not
+ * what happened.
+ */
+export declare function failureFacts(errors: readonly {
+    message?: string;
+}[] | undefined, steps: readonly StepLike[] | undefined): TestFailureFacts | undefined;
+/**
+ * The slowest LEAF steps.
+ *
+ * Leaves only, and that is the load-bearing decision. Playwright's step tree
+ * nests, and a parent's duration CONTAINS its children's — so a list mixing the
+ * two double-counts, and "the slowest step took 8s" would be answered by a
+ * wrapper whose children did all the work. Leaves are the actual operations.
+ *
+ * The cost of that choice, stated: a slow custom step that wraps many fast ones
+ * will not appear, even though it is arguably the interesting row. Reporting both
+ * would need a tree in the output, and the useful artefact here is a short list.
+ */
+export declare function slowestSteps(steps: readonly StepLike[] | undefined, limit?: number): SlowStep[];
+export interface WorkerLoad {
+    /**
+     * Distinct worker PROCESSES that ran at least one test.
+     *
+     * **Not the parallelism.** Playwright recycles workers — a new process per
+     * project, and another after a worker dies — so a strictly serial suite still
+     * reports several. Measured on the SDK's own fixture suite: `workers: 1` in the
+     * config, five worker indices across five projects.
+     *
+     * `configured` below is the parallelism, and it is what decides whether any of
+     * this is worth showing.
+     */
+    workers: number;
+    /**
+     * `workers` from the Playwright config, when the caller knows it.
+     *
+     * Load below is only an IMBALANCE if more than one worker could run at once. On
+     * a serial suite the spread between processes is just the shape of the projects,
+     * and presenting it as imbalance would be a confident wrong answer — which is
+     * how this field came to exist: the first version reported `tailMs: 6350` on a
+     * one-worker run and read as a serious finding.
+     *
+     * Absent when the config could not be read; renderers must then withhold the
+     * imbalance framing rather than assume parallelism.
+     */
+    configured?: number;
+    /** Busy milliseconds on the busiest worker process. */
+    busiestMs: number;
+    /** Busy milliseconds on the least busy worker process. */
+    idlestMs: number;
+    /**
+     * How far the busiest worker sits above the median.
+     *
+     * Meaningful only when `configured` is greater than 1, where a large value means
+     * one worker is holding the run open while the others are idle — the commonest
+     * cheap CI win. On a serial run it is an artefact and must not be shown.
+     */
+    tailMs: number;
+}
+/**
+ * Per-worker busy time.
+ *
+ * **Busy time, never wall clock.** These are summed test durations, so the total
+ * across workers exceeds the run's elapsed time by roughly the parallelism factor.
+ * Nothing may present these as "the run took X" or subtract them from anything —
+ * the same discipline scan overhead follows, and for the same reason: we can
+ * measure what we spent, not what the run would have cost without it.
+ *
+ * `undefined` when no outcome carried a worker index, which is the honest answer
+ * for a run where Playwright never told us (and for envelopes written before the
+ * field existed). Renderers must then say nothing rather than reporting one
+ * worker.
+ */
+export declare function workerLoad(outcomes: readonly {
+    workerIndex?: number;
+    durationMs: number;
+}[], configured?: number): WorkerLoad | undefined;
+export interface FlakyTest {
+    testId: string;
+    /** Which attempt finally passed. */
+    passedOnRetry: number;
+    /** How the earliest failing attempt failed, when the result said. */
+    failure?: TestFailureFacts;
+}
+/**
+ * Tests that failed and then passed, itemised.
+ *
+ * The summary already says "2 flaky". It does not say WHICH, on which attempt, or
+ * on which step — and all three are already in the data, which is the whole
+ * complaint. No schema change was needed for this; it is a projection over
+ * `(testId, retry, status)` plus the failure facts captured alongside.
+ */
+interface Attempt {
+    testId: string;
+    retry: number;
+    status: string;
+    failure?: TestFailureFacts;
+}
+export declare function flakyTests(outcomes: readonly Attempt[]): FlakyTest[];
+export interface OverheadFacts {
+    scans: number;
+    scanMs: number;
+    axeMs: number;
+    runDurationMs: number;
+}
+export interface SuiteFacts {
+    slowestTests: {
+        testId: string;
+        durationMs: number;
+    }[];
+    slowestSteps: {
+        testId: string;
+        title: string;
+        category: string;
+        durationMs: number;
+    }[];
+    workers?: WorkerLoad;
+    flaky: FlakyTest[];
+}
+/**
+ * The shape `localFacts` needs, described structurally rather than imported.
+ *
+ * `TestOutcome` lives in `envelope.ts` and `RunMeta` in `contract.ts`, and both
+ * already depend on this module for `FlakyTest`/`WorkerLoad`. Naming the input
+ * structurally keeps the dependency pointing one way — and it is what lets both
+ * the solo reporter and the run-group merge call this with their own arrays.
+ */
+export interface OutcomeLike {
+    testId: string;
+    durationMs: number;
+    retry: number;
+    status: string;
+    workerIndex?: number;
+    failure?: TestFailureFacts;
+    slowestSteps?: SlowStep[];
+    records: readonly {
+        kind: string;
+        cost?: {
+            totalMs: number;
+            axeMs: number;
+        };
+    }[];
+}
+/**
+ * The local-only suite/overhead/coverage blocks for `meta.json`.
+ *
+ * Assembled in one place because all three are reductions over the same
+ * `outcomes` array, and because a renderer recomputing any of them is how the
+ * terminal, the HTML report and the markdown output come to disagree.
+ */
+export declare function localFacts(outcomes: readonly OutcomeLike[], runDurationMs: number, configuredWorkers?: number): {
+    overhead?: OverheadFacts;
+    suite: SuiteFacts;
+};
+export {};
+//# sourceMappingURL=suite.d.ts.map