@nayaverse/overflow 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# @nayaverse/overflow
 
-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.
+**Find horizontal overflow at every breakpoint, in CI, and name the element.**
+
+Zero dependencies. Node 20+. Works through Playwright, Puppeteer, or on its
+own.
+
+```bash
+npm i -D @nayaverse/overflow
+```
+
+---
+
+## Why this is not already solved
+
+The problem is old and well written up —
+[Smashing Magazine](https://www.smashingmagazine.com/2021/04/css-overflow-issues/),
+[CSS-Tricks](https://css-tricks.com/?p=175021),
+[Polypane](https://polypane.app/blog/strategies-for-dealing-with-horizontal-overflows/) —
+and the technique is agreed: compare `scrollWidth` to `clientWidth`, then find
+the elements whose right edge passes the viewport.
+
+What you can actually install is a
+[Chrome extension](https://chrome.google.com/webstore/detail/overflow-detector/gpdnihamialibcjfmdnfbjcljnfbgkbc/reviews),
+a paid browser like [Polypane](https://polypane.app/) or
+[Sizzy](https://sizzy.co/blog/fix-horizontal-scroll), or a console snippet.
+All of them need a person to be looking, at one viewport, at one moment.
+
+Nothing packaged **fails a build** across a list of breakpoints and tells you
+which element to change.
+
+---
+
+## Use
+
+### Standalone
+
+```bash
+# any Chrome with remote debugging
+chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/ovf about:blank
+
+npx overflow https://example.com
+npx overflow https://example.com --widths 320,390,768 --tolerance 2
+```
+
+```
+  320px  OVERFLOW 434px — table#wide-table
+  390px  OVERFLOW 364px — table#wide-table
+  768px  ok
+
+320px viewport scrolls to 754px (434px of overflow)
+  table#wide-table
+    reaches 434px past the edge; it is 738px wide in a 320px viewport
+    html > body > div.frame > table#wide-table
+
+Horizontal overflow at 320, 390px.
+```
+
+Exit code is 1 when anything overflowed, so it gates a deploy.
+
+### With Playwright
+
+Prefer this if you already have Playwright — it sets the viewport correctly
+by default, which is the part that matters.
+
+```ts
+import { sweepPage } from '@nayaverse/overflow/playwright';
+
+test('no horizontal overflow', async ({ page }) => {
+  await page.goto('/');
+  const result = await sweepPage(page, { widths: [320, 390, 768, 1280] });
+  expect(result.ok, result.report()).toBe(true);
+});
+```
+
+`sweepPage` restores the viewport afterwards, so the next assertion in the
+same test does not fail for a reason that is not its own.
+
+### With anything else
+
+```ts
+import { checkViewport } from '@nayaverse/overflow';
+
+const analysis = await checkViewport((expr) => page.evaluate(expr));
+if (analysis.overflow > 0) console.log(analysis.causes);
+```
+
+`evaluate` is any function that runs a JavaScript expression in the page and
+returns its value. Puppeteer, Playwright, a raw CDP session, or your own.
+
+---
+
+## What makes the output usable
+
+Detection is the easy half. A sweep that reports every element whose right
+edge passes the viewport produces dozens of findings, most of them children
+of one real cause and several of them perfectly fine — and a check that cries
+wolf gets switched off, after which it catches nothing.
+
+So three things are dismissed, with the reason recorded in `analysis.dismissed`:
+
+**An element inside a horizontal scroller.** A tab strip in
+`overflow-x: auto` has a right edge far past the viewport and is doing
+exactly what it was built to do. An early version of this reported six of
+those while the real cause — a table elsewhere — sat unmentioned.
+
+**A fixed or sticky element.** Out of flow, so it does not extend the
+document.
+
+**Children carried by a wider parent.** A 738px table in a 320px viewport
+pushes its cells past the edge too. Reporting five 90px `<td>` elements is
+true and useless; the table is the thing you can change. When something is
+genuinely wider than the viewport, the **outermost** such element is blamed.
+When nothing is oversized and an element is merely pushed right by a margin,
+the rule inverts and the **innermost** is blamed, because there is no
+oversized ancestor to point at.
+
+And when the page overflows but nothing can be blamed, it says so rather than
+passing — a margin, a transform or a pseudo-element is usually the answer, and
+silence would read as success.
+
+---
+
+## The viewport trap this exists to avoid
+
+**On Windows, Chrome cannot open a window narrower than about 494px.**
+
+Launch with `--window-size=390,844` and the page lays out at 494px and is then
+clipped to 390 — which looks exactly like a horizontal overflow bug, in a
+layout that is completely fine. It is possible to spend hours fixing something
+that was never broken. (That is not hypothetical; it is why this package
+exists.)
+
+The bundled driver always sets the viewport with
+`Emulation.setDeviceMetricsOverride`, never a window size. Playwright does the
+right thing by default, which is why most people never meet this — but anyone
+driving Chrome directly walks straight into it.
+
+---
+
+## API
+
+### `sweep(options)`
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `url` | `string` | — | page to check |
+| `widths` | `number[]` | `320,360,390,414,768,1024,1440` | |
+| `height` | `number` | `900` | |
+| `settleMs` | `number` | `600` | wait after navigation for layout |
+| `tolerance` | `number` | `1` | sub-pixel rounding is normal |
+| `maxCauses` | `number` | `10` | |
+| `cdp.endpoint` | `string` | `http://127.0.0.1:9222` | |
+
+### `checkViewport(evaluate, options)` → `Analysis`
+
+```ts
+type Analysis = {
+  viewport: number;
+  scrollWidth: number;
+  overflow: number;           // <= 0 means it fits
+  causes: Cause[];            // what to change
+  dismissed: { selector: string; why: string }[];
+};
+```
+
+### `sweepPage(page, options)` — Playwright
+### `analyse(measurements, viewport, scrollWidth, options)` — the pure judgement, if you collect measurements yourself
+
+---
+
+## Tests
+
+The judgement is a pure function, so it is tested without a browser: thirteen
+cases covering each dismissal rule, both blame directions, ordering, capping,
+tolerance, and the overflow nobody can be blamed for.
+
+The collection half is proven against real Chrome on fixtures built to be
+wrong in known ways — a page that fits, a page with an oversized table, a page
+whose only overflow is a scroller and a sticky header, and a page with both,
+where only the table may be reported.
+
+## Licence
+
+MIT.

package/dist/src/analyse.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Deciding which elements actually cause a horizontal overflow.
+ *
+ * Kept pure, and separate from the browser, for one reason: this is where a
+ * tool like this is useful or useless. Reporting every element whose right
+ * edge exceeds the viewport produces dozens of findings, most of them
+ * children of one real cause and several of them inside a scroller that is
+ * supposed to scroll. A check that cries wolf gets switched off, and then it
+ * catches nothing at all.
+ *
+ * Being pure, it is also testable without a browser, which is why the rules
+ * below have tests rather than hopes.
+ */
+/** One element, as measured in the page. */
+export type Measured = {
+    /** A readable selector, for a human to go and look at. */
+    selector: string;
+    /** Ancestor chain, outermost first. Used to find leaves. */
+    path: string;
+    left: number;
+    right: number;
+    width: number;
+    /** An ancestor clips horizontally and holds this element inside itself. */
+    clipped: boolean;
+    /** position: fixed or sticky. */
+    fixed: boolean;
+    /** Depth from <html>. */
+    depth: number;
+};
+export type Cause = {
+    selector: string;
+    path: string;
+    /** How far past the viewport it reaches, in px. */
+    exceedsBy: number;
+    width: number;
+    left: number;
+    right: number;
+    /** Why this one is reported and others were not. */
+    why: string;
+};
+export type Analysis = {
+    viewport: number;
+    scrollWidth: number;
+    /** scrollWidth - viewport. Zero or less means no overflow. */
+    overflow: number;
+    causes: Cause[];
+    /** Flagged, then dismissed, with the reason. Kept so the tool can explain
+     *  itself when somebody insists there is a bug it did not report. */
+    dismissed: {
+        selector: string;
+        why: string;
+    }[];
+};
+export type AnalyseOptions = {
+    /** Sub-pixel layout and scrollbar rounding make a 1px "overflow" normal. */
+    tolerance?: number;
+    /** Most reports are one cause and its children. */
+    maxCauses?: number;
+};
+export declare function analyse(measurements: Measured[], viewport: number, scrollWidth: number, options?: AnalyseOptions): Analysis;
+/** A short line per cause, for a terminal or a CI annotation. */
+export declare function explain(a: Analysis): string[];
+//# sourceMappingURL=analyse.d.ts.map

package/dist/src/analyse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyse.d.ts","sourceRoot":"","sources":["../../src/analyse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG;IACrB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB;yEACqE;IACrE,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,OAAO,CACrB,YAAY,EAAE,QAAQ,EAAE,EACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,cAAmB,GAC3B,QAAQ,CA2FV;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,EAAE,CAkB7C"}

package/dist/src/analyse.js

@@ -0,0 +1,118 @@
+/**
+ * Deciding which elements actually cause a horizontal overflow.
+ *
+ * Kept pure, and separate from the browser, for one reason: this is where a
+ * tool like this is useful or useless. Reporting every element whose right
+ * edge exceeds the viewport produces dozens of findings, most of them
+ * children of one real cause and several of them inside a scroller that is
+ * supposed to scroll. A check that cries wolf gets switched off, and then it
+ * catches nothing at all.
+ *
+ * Being pure, it is also testable without a browser, which is why the rules
+ * below have tests rather than hopes.
+ */
+export function analyse(measurements, viewport, scrollWidth, options = {}) {
+    const { tolerance = 1, maxCauses = 10 } = options;
+    const overflow = scrollWidth - viewport;
+    const result = { viewport, scrollWidth, overflow, causes: [], dismissed: [] };
+    if (overflow <= tolerance)
+        return result;
+    const dismiss = (m, why) => result.dismissed.push({ selector: m.selector, why });
+    const candidates = [];
+    for (const m of measurements) {
+        if (m.width <= 0) {
+            dismiss(m, 'zero width');
+            continue;
+        }
+        if (m.right <= viewport + tolerance) {
+            // Does not reach past the edge at all.
+            continue;
+        }
+        if (m.clipped) {
+            // The tab strip inside overflow-x: auto. Its right edge is genuinely
+            // past the viewport and it is genuinely not the problem -- an earlier
+            // version of this check reported six of these and the real cause was a
+            // table somewhere else entirely.
+            dismiss(m, 'inside a horizontally scrollable ancestor, so it is clipped, not causing');
+            continue;
+        }
+        if (m.fixed) {
+            // A fixed element is out of flow and does not extend the document.
+            dismiss(m, 'position is fixed or sticky, so it does not extend the document');
+            continue;
+        }
+        candidates.push(m);
+    }
+    // Two different shapes of cause, and they want opposite rules.
+    //
+    // Something genuinely wider than the viewport -- a table, a pre, an image
+    // with a fixed width -- is the thing to fix, and its children are merely
+    // carried along by it. Reporting those children is useless: a first version
+    // of this blamed five 90px <td> cells for a 720px table, which tells you
+    // nothing you can act on. So for these, report the OUTERMOST.
+    //
+    // Something that fits but starts too far right -- a badge pushed by a
+    // margin, an absolutely positioned decoration -- has no oversized ancestor
+    // to blame, and there the innermost element is the one with the offending
+    // geometry.
+    const tooWide = candidates.filter((m) => m.width > viewport + tolerance);
+    const pushedOut = candidates.filter((m) => m.width <= viewport + tolerance);
+    let blamed;
+    if (tooWide.length > 0) {
+        blamed = tooWide.filter((m) => {
+            const outer = tooWide.find((other) => other !== m && m.path.startsWith(other.path + ' > '));
+            if (outer) {
+                dismiss(m, `carried by ${outer.selector}, which is the wider element`);
+                return false;
+            }
+            return true;
+        });
+        for (const m of pushedOut) {
+            dismiss(m, 'fits the viewport; it is pushed out by a wider ancestor already reported');
+        }
+    }
+    else {
+        blamed = pushedOut.filter((m) => {
+            const inner = pushedOut.find((other) => other !== m && other.path.startsWith(m.path + ' > '));
+            if (inner) {
+                dismiss(m, `contains ${inner.selector}, which is the more specific cause`);
+                return false;
+            }
+            return true;
+        });
+    }
+    result.causes = blamed
+        .map((m) => ({
+        selector: m.selector,
+        path: m.path,
+        exceedsBy: Math.round(m.right - viewport),
+        width: Math.round(m.width),
+        left: Math.round(m.left),
+        right: Math.round(m.right),
+        why: m.width > viewport
+            ? `it is ${Math.round(m.width)}px wide in a ${viewport}px viewport`
+            : `it starts at ${Math.round(m.left)}px and is ${Math.round(m.width)}px wide`,
+    }))
+        .sort((a, b) => b.exceedsBy - a.exceedsBy)
+        .slice(0, maxCauses);
+    return result;
+}
+/** A short line per cause, for a terminal or a CI annotation. */
+export function explain(a) {
+    if (a.overflow <= 0)
+        return [];
+    const lines = [
+        `${a.viewport}px viewport scrolls to ${a.scrollWidth}px (${a.overflow}px of overflow)`,
+    ];
+    if (a.causes.length === 0) {
+        lines.push('  no element could be blamed. Every candidate was clipped, fixed, or zero width.', '  A margin, a transform or a pseudo-element is the usual answer here.');
+        return lines;
+    }
+    for (const c of a.causes) {
+        lines.push(`  ${c.selector}`);
+        lines.push(`    reaches ${c.exceedsBy}px past the edge; ${c.why}`);
+        lines.push(`    ${c.path}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=analyse.js.map

package/dist/src/analyse.js.map

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

package/dist/src/cdp.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A minimal Chrome DevTools Protocol client.
+ *
+ * Zero dependencies, about a hundred lines, and it exists for one reason: the
+ * viewport has to be set with `Emulation.setDeviceMetricsOverride`, never with
+ * a window size.
+ *
+ * On Windows a Chrome window cannot be narrower than roughly 494px. Launch
+ * with `--window-size=390,844` and the page lays out at 494px and is then
+ * clipped to 390 — which looks exactly like a horizontal overflow bug, in a
+ * layout that is perfectly fine. Hours go into fixing something that was
+ * never broken. Playwright gets this right by default; anyone driving Chrome
+ * directly walks straight into it.
+ *
+ * If you already use Playwright, use the adapter in ./playwright.js instead.
+ * This driver is for pipelines that do not want a browser automation
+ * dependency to run one check.
+ */
+export type CdpOptions = {
+    /** A running Chrome with --remote-debugging-port. */
+    endpoint?: string;
+    /** Per-command timeout. */
+    timeoutMs?: number;
+};
+export declare class CdpSession {
+    #private;
+    private constructor();
+    static open(options?: CdpOptions): Promise<CdpSession>;
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Set the viewport the page actually sees.
+     *
+     * Device metrics, never a window size. See the note at the top of this file.
+     */
+    setViewport(width: number, height?: number, deviceScaleFactor?: number): Promise<void>;
+    goto(url: string, settleMs?: number): Promise<void>;
+    evaluate(expression: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=cdp.d.ts.map

package/dist/src/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/cdp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,UAAU,GAAG;IACvB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,qBAAa,UAAU;;IAQrB,OAAO;WAgBM,IAAI,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAuChE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB5E;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAM,EAAE,iBAAiB,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B"}

package/dist/src/cdp.js

@@ -0,0 +1,136 @@
+/**
+ * A minimal Chrome DevTools Protocol client.
+ *
+ * Zero dependencies, about a hundred lines, and it exists for one reason: the
+ * viewport has to be set with `Emulation.setDeviceMetricsOverride`, never with
+ * a window size.
+ *
+ * On Windows a Chrome window cannot be narrower than roughly 494px. Launch
+ * with `--window-size=390,844` and the page lays out at 494px and is then
+ * clipped to 390 — which looks exactly like a horizontal overflow bug, in a
+ * layout that is perfectly fine. Hours go into fixing something that was
+ * never broken. Playwright gets this right by default; anyone driving Chrome
+ * directly walks straight into it.
+ *
+ * If you already use Playwright, use the adapter in ./playwright.js instead.
+ * This driver is for pipelines that do not want a browser automation
+ * dependency to run one check.
+ */
+export class CdpSession {
+    #ws;
+    #id = 0;
+    #pending = new Map();
+    #timeoutMs;
+    #targetId;
+    #endpoint;
+    constructor(ws, targetId, endpoint, timeoutMs) {
+        this.#ws = ws;
+        this.#targetId = targetId;
+        this.#endpoint = endpoint;
+        this.#timeoutMs = timeoutMs;
+        ws.addEventListener('message', (ev) => {
+            const msg = JSON.parse(String(ev.data));
+            if (msg.id === undefined)
+                return;
+            const p = this.#pending.get(msg.id);
+            if (!p)
+                return;
+            this.#pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new Error(`CDP: ${JSON.stringify(msg.error)}`));
+            else
+                p.resolve(msg.result);
+        });
+    }
+    static async open(options = {}) {
+        const endpoint = options.endpoint ?? 'http://127.0.0.1:9222';
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        if (typeof WebSocket === 'undefined') {
+            throw new Error('overflow: this Node has no global WebSocket, which the bundled CDP driver needs.\n' +
+                'Use Node 22+, or run the check through Playwright with ' +
+                "`import { checkPage } from '@nayaverse/overflow/playwright'`.");
+        }
+        let target;
+        try {
+            const res = await fetch(`${endpoint}/json/new?about:blank`, { method: 'PUT' });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            target = (await res.json());
+        }
+        catch (err) {
+            throw new Error(`overflow: could not reach Chrome at ${endpoint} (${err instanceof Error ? err.message : err}).\n` +
+                'Start one with:\n' +
+                '  chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/overflow-profile about:blank');
+        }
+        const ws = new WebSocket(target.webSocketDebuggerUrl);
+        await new Promise((resolve, reject) => {
+            ws.addEventListener('open', () => resolve(), { once: true });
+            ws.addEventListener('error', () => reject(new Error('overflow: CDP socket failed to open')), {
+                once: true,
+            });
+        });
+        const session = new CdpSession(ws, target.id, endpoint, timeoutMs);
+        await session.send('Page.enable');
+        await session.send('Runtime.enable');
+        return session;
+    }
+    send(method, params = {}) {
+        const id = ++this.#id;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`overflow: CDP ${method} timed out after ${this.#timeoutMs}ms`));
+            }, this.#timeoutMs);
+            this.#pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.#ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    /**
+     * Set the viewport the page actually sees.
+     *
+     * Device metrics, never a window size. See the note at the top of this file.
+     */
+    async setViewport(width, height = 900, deviceScaleFactor = 1) {
+        await this.send('Emulation.setDeviceMetricsOverride', {
+            width,
+            height,
+            deviceScaleFactor,
+            mobile: width < 768,
+        });
+    }
+    async goto(url, settleMs = 500) {
+        await this.send('Page.navigate', { url });
+        // Loading is not the same as laid out. Fonts and late CSS move things.
+        await new Promise((r) => setTimeout(r, settleMs));
+    }
+    async evaluate(expression) {
+        const res = (await this.send('Runtime.evaluate', {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+        }));
+        if (res.exceptionDetails) {
+            throw new Error(`overflow: page threw: ${res.exceptionDetails.text ?? 'unknown'}`);
+        }
+        return res.result?.value;
+    }
+    async close() {
+        try {
+            await fetch(`${this.#endpoint}/json/close/${this.#targetId}`);
+        }
+        catch {
+            // The tab is going away either way.
+        }
+        this.#ws.close();
+    }
+}
+//# sourceMappingURL=cdp.js.map

package/dist/src/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/cdp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,MAAM,OAAO,UAAU;IACrB,GAAG,CAAY;IACf,GAAG,GAAG,CAAC,CAAC;IACR,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IACtC,UAAU,CAAS;IACnB,SAAS,CAAS;IAClB,SAAS,CAAS;IAElB,YAAoB,EAAa,EAAE,QAAgB,EAAE,QAAgB,EAAE,SAAiB;QACtF,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,EAAE,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAgB,EAAE,EAAE;YAClD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAuD,CAAC;YAC9F,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS;gBAAE,OAAO;YACjC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,CAAC;gBAAE,OAAO;YACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7B,IAAI,GAAG,CAAC,KAAK;gBAAE,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;;gBACnE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAsB,EAAE;QACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,uBAAuB,CAAC;QAC7D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;QAE9C,IAAI,OAAO,SAAS,KAAK,WAAW,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,oFAAoF;gBAClF,yDAAyD;gBACzD,+DAA+D,CAClE,CAAC;QACJ,CAAC;QAED,IAAI,MAAoD,CAAC;QACzD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,uBAAuB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACnD,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uCAAuC,QAAQ,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM;gBAChG,mBAAmB;gBACnB,wGAAwG,CAC3G,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACtD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,EAAE;gBAC3F,IAAI,EAAE,IAAI;aACX,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QACnE,MAAM,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClC,MAAM,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,MAAc,EAAE,SAAkC,EAAE;QACvD,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACzB,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,MAAM,oBAAoB,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;YACpF,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAEpB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE;gBACpB,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;oBACb,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,CAAC,CAAC,CAAC,CAAC;gBACb,CAAC;gBACD,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;oBACZ,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,MAAM,CAAC,CAAC,CAAC,CAAC;gBACZ,CAAC;aACF,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,MAAM,GAAG,GAAG,EAAE,iBAAiB,GAAG,CAAC;QAClE,MAAM,IAAI,CAAC,IAAI,CAAC,oCAAoC,EAAE;YACpD,KAAK;YACL,MAAM;YACN,iBAAiB;YACjB,MAAM,EAAE,KAAK,GAAG,GAAG;SACpB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW,EAAE,QAAQ,GAAG,GAAG;QACpC,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1C,uEAAuE;QACvE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,UAAkB;QAC/B,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YAC/C,UAAU;YACV,aAAa,EAAE,IAAI;YACnB,YAAY,EAAE,IAAI;SACnB,CAAC,CAA2E,CAAC;QAC9E,IAAI,GAAG,CAAC,gBAAgB,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,gBAAgB,CAAC,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,eAAe,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}

package/dist/src/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * overflow https://example.com
+ * overflow https://example.com --widths 320,390,768 --json
+ *
+ * Exits non-zero when the page scrolls sideways at any width. That is what
+ * makes it a gate rather than a report nobody reads.
+ */
+import { sweep, DEFAULT_WIDTHS } from './sweep.js';
+import { explain } from './analyse.js';
+const USAGE = [
+    'overflow - find horizontal overflow at every breakpoint, and name the element',
+    '',
+    '  overflow <url> [options]',
+    '',
+    'Options',
+    `  --widths a,b,c     viewport widths (default ${DEFAULT_WIDTHS.join(',')})`,
+    '  --height <n>       viewport height (default 900)',
+    '  --settle-ms <n>    wait after navigation for layout (default 600)',
+    '  --tolerance <n>    px of overflow to ignore (default 1)',
+    '  --endpoint <url>   running Chrome (default http://127.0.0.1:9222)',
+    '  --json             print the full result as JSON',
+    '',
+    'Needs a Chrome with remote debugging:',
+    '  chrome --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/ovf about:blank',
+    '',
+    'Already using Playwright? Use the adapter instead:',
+    "  import { sweepPage } from '@nayaverse/overflow/playwright'",
+].join('\n');
+function main() {
+    const argv = process.argv.slice(2);
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const [k, inline] = a.slice(2).split('=', 2);
+            if (inline !== undefined)
+                flags[k] = inline;
+            else if (argv[i + 1] && !argv[i + 1].startsWith('--'))
+                flags[k] = argv[++i];
+            else
+                flags[k] = true;
+        }
+        else
+            rest.push(a);
+    }
+    if (flags.help || flags.h || rest.length === 0) {
+        console.log(USAGE);
+        process.exit(rest.length === 0 ? 1 : 0);
+    }
+    const url = rest[0];
+    const widths = typeof flags.widths === 'string'
+        ? flags.widths
+            .split(',')
+            .map((w) => Number(w.trim()))
+            .filter((n) => Number.isFinite(n) && n > 0)
+        : [...DEFAULT_WIDTHS];
+    if (widths.length === 0) {
+        console.error('overflow: --widths had no usable numbers');
+        process.exit(1);
+    }
+    const num = (k, d) => (flags[k] === undefined ? d : Number(flags[k]));
+    sweep({
+        url,
+        widths,
+        height: num('height', 900),
+        settleMs: num('settle-ms', 600),
+        tolerance: num('tolerance', 1),
+        ...(typeof flags.endpoint === 'string' ? { cdp: { endpoint: flags.endpoint } } : {}),
+        onProgress: flags.json ? () => { } : (line) => console.log(line),
+    })
+        .then((result) => {
+        if (flags.json) {
+            console.log(JSON.stringify(result.results, null, 2));
+        }
+        else if (!result.ok) {
+            // The one-line-per-width summary already streamed through onProgress.
+            // What follows is the detail for the widths that failed, in full:
+            // the selector, how far it reaches, and where it sits in the tree.
+            console.log('');
+            for (const r of result.results) {
+                if (r.overflow > 0)
+                    for (const line of explain(r))
+                        console.log(line);
+            }
+            console.log('');
+            console.log(`Horizontal overflow at ${result.failedAt.join(', ')}px.`);
+        }
+        else {
+            console.log('');
+            console.log(`No horizontal overflow at any of ${result.results.length} width(s).`);
+        }
+        process.exit(result.ok ? 0 : 1);
+    })
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,KAAK,GAAG;IACZ,+EAA+E;IAC/E,EAAE;IACF,4BAA4B;IAC5B,EAAE;IACF,SAAS;IACT,iDAAiD,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG;IAC5E,oDAAoD;IACpD,qEAAqE;IACrE,2DAA2D;IAC3D,qEAAqE;IACrE,oDAAoD;IACpD,EAAE;IACF,uCAAuC;IACvC,2FAA2F;IAC3F,EAAE;IACF,oDAAoD;IACpD,8DAA8D;CAC/D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,SAAS,IAAI;IACX,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAC7C,IAAI,MAAM,KAAK,SAAS;gBAAE,KAAK,CAAC,CAAE,CAAC,GAAG,MAAM,CAAC;iBACxC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,CAAE,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAE,CAAC;;gBAC1E,KAAK,CAAC,CAAE,CAAC,GAAG,IAAI,CAAC;QACxB,CAAC;;YAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;IACrB,MAAM,MAAM,GACV,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAC9B,CAAC,CAAC,KAAK,CAAC,MAAM;aACT,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;aAC5B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC;IAE1B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtF,KAAK,CAAC;QACJ,GAAG;QACH,MAAM;QACN,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC;QAC1B,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC;QAC/B,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;QAC9B,GAAG,CAAC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpF,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;KACxE,CAAC;SACC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QACf,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACtB,sEAAsE;YACtE,kEAAkE;YAClE,mEAAmE;YACnE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC/B,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC;oBAAE,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;wBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvE,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,0BAA0B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,oCAAoC,MAAM,CAAC,OAAO,CAAC,MAAM,YAAY,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACtB,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/src/collect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The part that has to run inside the page.
+ *
+ * Shipped as a string so it can be handed to anything that evaluates
+ * JavaScript in a browser — Playwright's `page.evaluate`, Puppeteer's, a raw
+ * CDP `Runtime.evaluate`, or a `<script>` tag in a console. That is what makes
+ * this usable without choosing a browser driver for you.
+ *
+ * It only measures. Every judgement lives in analyse.ts, where it can be
+ * tested without a browser.
+ */
+/** Matches the Measured type in analyse.ts. Kept in sync by the round-trip
+ *  test rather than by a shared import, because this code is serialised. */
+export declare const COLLECT_SOURCE: string;
+export type Collected = {
+    viewport: number;
+    scrollWidth: number;
+    measurements: import('./analyse.js').Measured[];
+};
+/** Anything that can run a JavaScript expression in the page and give back
+ *  the value. `page.evaluate` in Playwright and Puppeteer both satisfy it. */
+export type Evaluate = (expression: string) => Promise<unknown>;
+export declare function collect(evaluate: Evaluate): Promise<Collected>;
+//# sourceMappingURL=collect.d.ts.map

package/dist/src/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;4EAC4E;AAC5E,eAAO,MAAM,cAAc,QAwE1B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,cAAc,EAAE,QAAQ,EAAE,CAAC;CACjD,CAAC;AAEF;8EAC8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhE,wBAAsB,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CASpE"}

package/dist/src/collect.js

@@ -0,0 +1,95 @@
+/**
+ * The part that has to run inside the page.
+ *
+ * Shipped as a string so it can be handed to anything that evaluates
+ * JavaScript in a browser — Playwright's `page.evaluate`, Puppeteer's, a raw
+ * CDP `Runtime.evaluate`, or a `<script>` tag in a console. That is what makes
+ * this usable without choosing a browser driver for you.
+ *
+ * It only measures. Every judgement lives in analyse.ts, where it can be
+ * tested without a browser.
+ */
+/** Matches the Measured type in analyse.ts. Kept in sync by the round-trip
+ *  test rather than by a shared import, because this code is serialised. */
+export const COLLECT_SOURCE = String.raw `
+(function () {
+  var doc = document.documentElement;
+  var viewport = doc.clientWidth;
+  var scrollWidth = doc.scrollWidth;
+
+  function label(el) {
+    var name = el.tagName.toLowerCase();
+    if (el.id) return name + '#' + el.id;
+    var cls = (el.getAttribute('class') || '').trim().split(/\s+/).filter(Boolean);
+    if (cls.length) {
+      // Three classes is enough to find it; a utility-class soup is not.
+      return name + '.' + cls.slice(0, 3).join('.') + (cls.length > 3 ? '…' : '');
+    }
+    return name;
+  }
+
+  function pathOf(el) {
+    var parts = [];
+    for (var n = el; n && n.nodeType === 1 && n !== doc.parentNode; n = n.parentElement) {
+      parts.unshift(label(n));
+      if (parts.length > 6) break;
+    }
+    return parts.join(' > ');
+  }
+
+  // An ancestor that scrolls or clips horizontally, and whose own right edge
+  // is inside the viewport, is holding this element rather than being pushed
+  // by it.
+  function clippedBy(el) {
+    for (var n = el.parentElement; n && n !== doc; n = n.parentElement) {
+      var s = getComputedStyle(n);
+      var ox = s.overflowX;
+      if (ox === 'auto' || ox === 'scroll' || ox === 'hidden' || ox === 'clip') {
+        if (n.getBoundingClientRect().right <= viewport + 1) return true;
+      }
+    }
+    return false;
+  }
+
+  var out = [];
+  var all = document.body ? document.body.querySelectorAll('*') : [];
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i];
+    var r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0) continue;
+    if (r.right <= viewport + 1) continue;
+
+    var style = getComputedStyle(el);
+    var position = style.position;
+
+    var depth = 0;
+    for (var p = el; p; p = p.parentElement) depth++;
+
+    out.push({
+      selector: label(el),
+      path: pathOf(el),
+      left: r.left,
+      right: r.right,
+      width: r.width,
+      clipped: clippedBy(el),
+      fixed: position === 'fixed' || position === 'sticky',
+      depth: depth
+    });
+
+    // A page with thousands of overflowing elements has one cause and a lot
+    // of children; the first few hundred are more than enough to find it.
+    if (out.length >= 400) break;
+  }
+
+  return { viewport: viewport, scrollWidth: scrollWidth, measurements: out };
+})()
+`;
+export async function collect(evaluate) {
+    const raw = (await evaluate(COLLECT_SOURCE));
+    if (!raw || typeof raw.viewport !== 'number') {
+        throw new Error('overflow: the page returned no measurements. The evaluate function must ' +
+            'return the expression value, not a handle to it.');
+    }
+    return raw;
+}
+//# sourceMappingURL=collect.js.map

package/dist/src/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../../src/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;4EAC4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwEvC,CAAC;AAYF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAkB;IAC9C,MAAM,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,cAAc,CAAC,CAA0B,CAAC;IACtE,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { analyse, explain } from './analyse.js';
+export type { Measured, Cause, Analysis, AnalyseOptions } from './analyse.js';
+export { collect, COLLECT_SOURCE } from './collect.js';
+export type { Collected, Evaluate } from './collect.js';
+export { checkViewport, sweep, sweepWith, DEFAULT_WIDTHS } from './sweep.js';
+export type { SweepOptions, SweepResult } from './sweep.js';
+export { CdpSession } from './cdp.js';
+export type { CdpOptions } from './cdp.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { analyse, explain } from './analyse.js';
+export { collect, COLLECT_SOURCE } from './collect.js';
+export { checkViewport, sweep, sweepWith, DEFAULT_WIDTHS } from './sweep.js';
+export { CdpSession } from './cdp.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/src/playwright.d.ts

@@ -0,0 +1,34 @@
+import { type Analysis, type AnalyseOptions } from './analyse.js';
+/** The shape this needs from a Playwright Page. */
+export type PlaywrightPage = {
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    evaluate<R>(fn: string): Promise<R>;
+    viewportSize(): {
+        width: number;
+        height: number;
+    } | null;
+};
+/** Check the page as it is, at its current viewport. */
+export declare function checkPage(page: PlaywrightPage, options?: AnalyseOptions): Promise<Analysis>;
+export type PlaywrightSweepOptions = AnalyseOptions & {
+    widths?: readonly number[];
+    height?: number;
+    onProgress?: (line: string) => void;
+};
+export type PlaywrightSweepResult = {
+    ok: boolean;
+    results: Analysis[];
+    failedAt: number[];
+    report(): string;
+};
+/**
+ * Check every width, then put the viewport back where it was.
+ *
+ * Restoring matters: a check that silently leaves the page at 320px makes the
+ * next assertion in the same test fail for a reason that is not its own.
+ */
+export declare function sweepPage(page: PlaywrightPage, options?: PlaywrightSweepOptions): Promise<PlaywrightSweepResult>;
+//# sourceMappingURL=playwright.d.ts.map

package/dist/src/playwright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.d.ts","sourceRoot":"","sources":["../../src/playwright.ts"],"names":[],"mappings":"AAUA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3E,mDAAmD;AACnD,MAAM,MAAM,cAAc,GAAG;IAC3B,eAAe,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpC,YAAY,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC1D,CAAC;AAEF,wDAAwD;AACxD,wBAAsB,SAAS,CAC7B,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IACpD,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,IAAI,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC,CA8BhC"}

package/dist/src/playwright.js

@@ -0,0 +1,50 @@
+/**
+ * Playwright adapter.
+ *
+ * No dependency on Playwright: the page is accepted structurally, so this
+ * compiles and ships whether or not Playwright is installed. If you already
+ * use Playwright, prefer this over the bundled CDP driver — Playwright
+ * already sets the viewport with device metrics, which is the part that
+ * matters.
+ */
+import { checkViewport, DEFAULT_WIDTHS } from './sweep.js';
+import { explain } from './analyse.js';
+/** Check the page as it is, at its current viewport. */
+export async function checkPage(page, options = {}) {
+    return checkViewport((expr) => page.evaluate(expr), options);
+}
+/**
+ * Check every width, then put the viewport back where it was.
+ *
+ * Restoring matters: a check that silently leaves the page at 320px makes the
+ * next assertion in the same test fail for a reason that is not its own.
+ */
+export async function sweepPage(page, options = {}) {
+    const { widths = DEFAULT_WIDTHS, height = 900, onProgress = () => { }, ...rest } = options;
+    const original = page.viewportSize();
+    const results = [];
+    try {
+        for (const width of widths) {
+            await page.setViewportSize({ width, height });
+            const analysis = await checkPage(page, rest);
+            results.push(analysis);
+            onProgress(analysis.overflow > 0
+                ? `${String(width).padStart(5)}px  OVERFLOW ${analysis.overflow}px`
+                : `${String(width).padStart(5)}px  ok`);
+        }
+    }
+    finally {
+        if (original)
+            await page.setViewportSize(original);
+    }
+    const failedAt = results.filter((r) => r.overflow > 0).map((r) => r.viewport);
+    return {
+        ok: failedAt.length === 0,
+        results,
+        failedAt,
+        report: () => results
+            .flatMap((r) => (r.overflow > 0 ? explain(r) : [`${String(r.viewport).padStart(5)}px  ok`]))
+            .join('\n'),
+    };
+}
+//# sourceMappingURL=playwright.js.map

package/dist/src/playwright.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.js","sourceRoot":"","sources":["../../src/playwright.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAsC,MAAM,cAAc,CAAC;AAS3E,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAoB,EACpB,UAA0B,EAAE;IAE5B,OAAO,aAAa,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC;AAeD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAoB,EACpB,UAAkC,EAAE;IAEpC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,MAAM,GAAG,GAAG,EAAE,UAAU,GAAG,GAAG,EAAE,GAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACrC,MAAM,OAAO,GAAe,EAAE,CAAC;IAE/B,IAAI,CAAC;QACH,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9C,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,UAAU,CACR,QAAQ,CAAC,QAAQ,GAAG,CAAC;gBACnB,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,IAAI;gBACnE,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CACzC,CAAC;QACJ,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,QAAQ;YAAE,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9E,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;QACzB,OAAO;QACP,QAAQ;QACR,MAAM,EAAE,GAAG,EAAE,CACX,OAAO;aACJ,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;aAC3F,IAAI,CAAC,IAAI,CAAC;KAChB,CAAC;AACJ,CAAC"}

package/dist/src/sweep.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Walk a set of viewport widths and report, for each, whether the page
+ * scrolls sideways and which element is responsible.
+ */
+import { type Analysis, type AnalyseOptions } from './analyse.js';
+import { type Evaluate } from './collect.js';
+import { type CdpOptions } from './cdp.js';
+/** The widths worth checking by default: the narrowest phone still in use,
+ *  the common Android and iPhone sizes, the large phone, the tablet, the
+ *  small laptop, and a desktop. */
+export declare const DEFAULT_WIDTHS: readonly [320, 360, 390, 414, 768, 1024, 1440];
+export type SweepResult = {
+    ok: boolean;
+    url?: string;
+    /** One per width, in the order checked. */
+    results: Analysis[];
+    /** Widths at which the page overflowed. */
+    failedAt: number[];
+    report(): string;
+};
+/**
+ * Check one already-loaded page at its current viewport.
+ *
+ * Use this when you own the browser: Playwright, Puppeteer, or your own CDP
+ * session. `evaluate` is anything that runs an expression in the page and
+ * returns its value.
+ */
+export declare function checkViewport(evaluate: Evaluate, options?: AnalyseOptions): Promise<Analysis>;
+export type SweepOptions = AnalyseOptions & {
+    url: string;
+    widths?: readonly number[];
+    /** Height for each check. Only matters for lazy content. */
+    height?: number;
+    /** Milliseconds to wait after navigation for layout to settle. */
+    settleMs?: number;
+    cdp?: CdpOptions;
+    onProgress?: (line: string) => void;
+};
+/**
+ * Open a page at each width and check it, using the bundled CDP driver.
+ *
+ * The viewport is set with device metrics rather than a window size, which is
+ * the only way to get an honest narrow viewport. See cdp.ts.
+ */
+export declare function sweep(options: SweepOptions): Promise<SweepResult>;
+/**
+ * Sweep using a browser you already drive.
+ *
+ * `setViewport` and `evaluate` are yours, so this works with Playwright,
+ * Puppeteer, or anything else, without this package depending on any of them.
+ */
+export declare function sweepWith(page: {
+    setViewport(width: number, height: number): Promise<void>;
+    evaluate: Evaluate;
+}, options?: Omit<SweepOptions, 'url' | 'cdp'> & {
+    url?: string;
+}): Promise<SweepResult>;
+//# sourceMappingURL=sweep.d.ts.map

package/dist/src/sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../src/sweep.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACpF,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAEvD;;mCAEmC;AACnC,eAAO,MAAM,cAAc,gDAAiD,CAAC;AAE7E,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,IAAI,MAAM,CAAC;CAClB,CAAC;AA6BF;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAGnB;AAED,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA+BvE;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE;IAAE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,EACvF,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,WAAW,CAAC,CAuBtB"}

package/dist/src/sweep.js

@@ -0,0 +1,94 @@
+/**
+ * Walk a set of viewport widths and report, for each, whether the page
+ * scrolls sideways and which element is responsible.
+ */
+import { analyse, explain } from './analyse.js';
+import { collect } from './collect.js';
+import { CdpSession } from './cdp.js';
+/** The widths worth checking by default: the narrowest phone still in use,
+ *  the common Android and iPhone sizes, the large phone, the tablet, the
+ *  small laptop, and a desktop. */
+export const DEFAULT_WIDTHS = [320, 360, 390, 414, 768, 1024, 1440];
+function makeResult(results, url) {
+    const failedAt = results.filter((r) => r.overflow > 0).map((r) => r.viewport);
+    return {
+        ok: failedAt.length === 0,
+        ...(url ? { url } : {}),
+        results,
+        failedAt,
+        report() {
+            const lines = [];
+            for (const r of results) {
+                if (r.overflow > 0) {
+                    lines.push(...explain(r));
+                }
+                else {
+                    lines.push(`${String(r.viewport).padStart(5)}px  ok`);
+                }
+            }
+            lines.push('');
+            lines.push(failedAt.length === 0
+                ? `No horizontal overflow at any of ${results.length} width(s).`
+                : `Horizontal overflow at ${failedAt.join(', ')}px.`);
+            return lines.join('\n');
+        },
+    };
+}
+/**
+ * Check one already-loaded page at its current viewport.
+ *
+ * Use this when you own the browser: Playwright, Puppeteer, or your own CDP
+ * session. `evaluate` is anything that runs an expression in the page and
+ * returns its value.
+ */
+export async function checkViewport(evaluate, options = {}) {
+    const { viewport, scrollWidth, measurements } = await collect(evaluate);
+    return analyse(measurements, viewport, scrollWidth, options);
+}
+/**
+ * Open a page at each width and check it, using the bundled CDP driver.
+ *
+ * The viewport is set with device metrics rather than a window size, which is
+ * the only way to get an honest narrow viewport. See cdp.ts.
+ */
+export async function sweep(options) {
+    const { url, widths = DEFAULT_WIDTHS, height = 900, settleMs = 600, cdp, onProgress = () => { }, ...analyseOptions } = options;
+    const session = await CdpSession.open(cdp ?? {});
+    const results = [];
+    try {
+        for (const width of widths) {
+            await session.setViewport(width, height);
+            await session.goto(url, settleMs);
+            const analysis = await checkViewport((e) => session.evaluate(e), analyseOptions);
+            results.push(analysis);
+            onProgress(analysis.overflow > 0
+                ? `${String(width).padStart(5)}px  OVERFLOW ${analysis.overflow}px — ${analysis.causes[0]?.selector ?? 'no element could be blamed'}`
+                : `${String(width).padStart(5)}px  ok`);
+        }
+    }
+    finally {
+        await session.close();
+    }
+    return makeResult(results, url);
+}
+/**
+ * Sweep using a browser you already drive.
+ *
+ * `setViewport` and `evaluate` are yours, so this works with Playwright,
+ * Puppeteer, or anything else, without this package depending on any of them.
+ */
+export async function sweepWith(page, options = {}) {
+    const { widths = DEFAULT_WIDTHS, height = 900, onProgress = () => { }, url, settleMs, ...analyseOptions } = options;
+    void settleMs;
+    const results = [];
+    for (const width of widths) {
+        await page.setViewport(width, height);
+        const analysis = await checkViewport(page.evaluate, analyseOptions);
+        results.push(analysis);
+        onProgress(analysis.overflow > 0
+            ? `${String(width).padStart(5)}px  OVERFLOW ${analysis.overflow}px`
+            : `${String(width).padStart(5)}px  ok`);
+    }
+    return makeResult(results, url);
+}
+//# sourceMappingURL=sweep.js.map

package/dist/src/sweep.js.map

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

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@nayaverse/overflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Find horizontal overflow at every breakpoint in CI, and name the element causing it.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/src/playwright.d.ts",
+      "default": "./dist/src/playwright.js"
+    }
+  },
+  "bin": {
+    "overflow": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "keywords": [
+    "responsive",
+    "overflow",
+    "horizontal-scroll",
+    "ci",
+    "breakpoints",
+    "css",
+    "testing",
+    "playwright",
+    "cdp"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/test/*.test.js",
+    "pretest": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/suhelali14/keel.git",
+    "directory": "packages/overflow"
+  },
+  "homepage": "https://github.com/suhelali14/keel/tree/main/packages/overflow#readme",
+  "bugs": {
+    "url": "https://github.com/suhelali14/keel/issues"
+  },
+  "author": "Suhelali Pakjade",
+  "sideEffects": false
+}