@juxtapose/core 0.4.0 → 0.5.0

package/dist/analysis/cause.js

@@ -0,0 +1,187 @@
+// Why did this story change? The cheap link only: the story's import
+// closure — a forward walk over the same Vite manifest `affected.ts` walks
+// backwards — intersected with the files changed since `--since`, nearest
+// first. `none-in-closure` beside `render-drift` is the strongest "this is
+// not your code" the tool can give. Matched CSS rules and source lines are
+// later rows.
+//
+// "Not your code" is said only after a full trace, and the manifest is
+// chunk-level, so a full trace needs two things:
+//
+// - Every node the walk reaches has its own manifest entry with a `src`. A
+//   Storybook build bundles components into chunks that have none, so a
+//   story's closure usually ends in an unresolved node; an `imports[]` key
+//   with no entry at all is the same. A changed file found before that point
+//   is a hit, but no hit is `unknown`. The first draft said "not your code"
+//   for a component edit on examples/storybook, the worst answer the
+//   feature can give.
+// - Every changed file is some entry's `src`. A module Rollup inlined into
+//   a chunk has no entry of its own, so a changed file the manifest never
+//   names could sit inside any chunk, this story's included. That holds for
+//   far more than code: JSON, SVG, GraphQL, `?raw` text, images and .mdx are
+//   all importable. So the exemption is an allowlist of files no bundler
+//   imports (prose docs, licences, git and editor dotfiles, `.github/`), and
+//   anything else unnamed blocks the claim. A list of bundled extensions
+//   failed open: every importable type it missed was a false "not yours".
+//
+// Even then the claim is about the traced imports, not about every byte the
+// story renders (a stylesheet linked from preview-head, a public asset), so
+// the wording says "likely".
+//
+// Nothing here may fail a story. `prepareCause` reads git and the manifest
+// on the first `causeFor` call, once, inside try/catch; that call happens
+// only in the fail branch of `judge()`, so a green run reads neither.
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { compareCodeUnits } from '../diff/structural/deltas.js';
+import { MAX_CAUSE_FILES } from '../diff/structural.js';
+import { gitChangedFiles, gitTopLevel, isConfigChange, isLockfileChange, isTsconfigChange, keyToSrc, loadViteManifest, toPosixRelative, } from './affected.js';
+const UNKNOWN = { kind: 'unknown', files: [] };
+/** The index from already-loaded inputs. Pure. */
+export function buildCauseIndex(src) {
+    const graph = src.manifest ? buildForwardGraph(src.manifest) : null;
+    return {
+        causeFor: async (componentPath) => causeOf(src, graph, componentPath),
+    };
+}
+/** The index for `jux run --since`. Lazy and memoized, so the manifest and
+ *  git are read once, and only if some story fails. */
+export function prepareCause(opts) {
+    let loading;
+    const load = async () => buildCauseIndex({
+        projectRoot: opts.projectRoot,
+        configDirs: opts.configDirs,
+        manifest: await orNull(() => opts.buildDir ? loadViteManifest(opts.buildDir) : Promise.resolve(null)),
+        changedFiles: await orNull(async () => projectRelative(gitChangedFiles(opts.sinceCommit, opts.projectRoot), gitTopLevel(opts.projectRoot), opts.projectRoot)),
+    });
+    return {
+        causeFor: async (componentPath) => {
+            try {
+                loading ??= load();
+                return await (await loading).causeFor(componentPath);
+            }
+            catch {
+                return UNKNOWN;
+            }
+        },
+    };
+}
+async function orNull(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return null;
+    }
+}
+/** Git prints paths relative to the repository top level; the manifest's
+ *  `src` is relative to the project root. In a monorepo these differ
+ *  (`examples/storybook/stories/X.jsx` vs `stories/X.jsx`), and comparing
+ *  them unmapped made every story `none-in-closure`. A file outside the
+ *  project maps to a `../` path, which is still what the manifest would hold
+ *  for it.
+ *
+ *  Git prints its top level with symlinks resolved, so the project root is
+ *  resolved too: on macOS the temp dir `/var/folders/…` is
+ *  `/private/var/folders/…` to git, and relating the two unresolved paths
+ *  gave `../../../../private/var/…` for every file, which matched nothing
+ *  and made a component edit `none-in-closure`. */
+function projectRelative(files, topLevel, projectRoot) {
+    if (files === null || topLevel === null)
+        return null;
+    const root = realpathSync(projectRoot);
+    return files.map((repoPath) => ({
+        path: toPosixRelative(root, path.join(topLevel, repoPath)),
+        repoPath,
+    }));
+}
+/** Files no bundler imports. `.mdx` is not one: it compiles to a module. */
+const NEVER_BUNDLED_EXT = /\.(?:md|markdown|mdown|rst|adoc)$/i;
+const NEVER_BUNDLED_NAME = /^(?:LICENSE.*|CHANGELOG.*|AUTHORS.*|CODEOWNERS|\.gitignore|\.gitattributes|\.editorconfig)$/;
+function neverBundled(f) {
+    const name = f.path.slice(f.path.lastIndexOf('/') + 1);
+    return (NEVER_BUNDLED_EXT.test(name) ||
+        NEVER_BUNDLED_NAME.test(name) ||
+        f.repoPath.startsWith('.github/'));
+}
+/** Reaches every story: a root lockfile or tsconfig, or a workbench config
+ *  dir. Checked in both forms, since a monorepo's root files are only
+ *  recognisable in git's. */
+function isGlobalChange(f, configDirs) {
+    return [f.path, f.repoPath].some((p) => isLockfileChange(p) || isTsconfigChange(p) || isConfigChange(p, configDirs));
+}
+function causeOf(src, graph, componentPath) {
+    if (src.changedFiles === null)
+        return UNKNOWN;
+    // Same rule as resolveAffected: these reach every story, so the closure
+    // is beside the point.
+    const global = src.changedFiles
+        .filter((f) => isGlobalChange(f, src.configDirs))
+        .map((f) => f.path)
+        .sort(compareCodeUnits);
+    if (global.length > 0) {
+        return {
+            kind: 'config',
+            files: global.slice(0, MAX_CAUSE_FILES).map((path) => ({ path, distance: 0 })),
+        };
+    }
+    if (!graph || componentPath === '')
+        return UNKNOWN;
+    const start = toPosixRelative(src.projectRoot, componentPath);
+    // Not in the graph (urls platform, a story outside the build): the
+    // closure was never traced, so "none of your files" would be a guess.
+    if (!graph.edges.has(start))
+        return UNKNOWN;
+    const reach = closure(graph.edges, start);
+    const changed = new Set(src.changedFiles.map((f) => f.path));
+    const files = [...reach]
+        .filter(([file]) => changed.has(file))
+        .map(([path, distance]) => ({ path, distance }))
+        .sort((x, y) => x.distance - y.distance || compareCodeUnits(x.path, y.path))
+        .slice(0, MAX_CAUSE_FILES);
+    // Fully traced: every node on the way had a src to look through, and no
+    // changed module could be hiding inlined in a chunk. A hit without it is
+    // still a hit, but not the whole answer: on examples/storybook a token edit
+    // bundled into the component chunk, beside a label edit in the story,
+    // named only the story file, for stories the token had changed.
+    const traced = [...reach.keys()].every((node) => graph.edges.has(node)) &&
+        src.changedFiles.every((f) => neverBundled(f) || graph.edges.has(f.path));
+    if (files.length > 0)
+        return traced
+            ? { kind: 'in-closure', files }
+            : { kind: 'in-closure', files, partial: true };
+    return traced ? { kind: 'none-in-closure', files: [] } : UNKNOWN;
+}
+/** Edges resolve through the same key → src map affected.ts's reverse graph
+ *  uses. A key with no src (a bundled chunk) or no entry at all stays a bare
+ *  key: reachable, never a key of `edges`. Entries that share a src (one
+ *  module emitted twice) merge their edges; overwriting dropped the first
+ *  entry's imports and could make a hit look like `none-in-closure`. */
+function buildForwardGraph(manifest) {
+    const srcOf = keyToSrc(manifest);
+    const edges = new Map();
+    for (const entry of Object.values(manifest)) {
+        if (!entry.src)
+            continue;
+        const out = [...(entry.imports ?? []), ...(entry.dynamicImports ?? [])].map((k) => srcOf.get(k) ?? k);
+        edges.set(entry.src, [...(edges.get(entry.src) ?? []), ...out]);
+    }
+    return { edges };
+}
+/** BFS distance from `start` to everything it reaches, `start` at 0. */
+function closure(edges, start) {
+    const dist = new Map([[start, 0]]);
+    const queue = [start];
+    for (let k = 0; k < queue.length; k++) {
+        const file = queue[k];
+        const d = dist.get(file);
+        for (const next of edges.get(file) ?? []) {
+            if (dist.has(next))
+                continue;
+            dist.set(next, d + 1);
+            queue.push(next);
+        }
+    }
+    return dist;
+}
+//# sourceMappingURL=cause.js.map

package/dist/analysis/cause.js.map

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

package/dist/baseline/approve.d.ts

@@ -0,0 +1,24 @@
+import type { ApprovalMeta, BaselineStore } from '../types.js';
+export interface RunStructure {
+    gz: Buffer;
+    structureHash: string;
+}
+/**
+ * The structure sidecar written beside a run capture (`<x>.webp` →
+ * `<x>.structure.json.gz`), or null when there is none.
+ *
+ * Structure explains a diff, it never gates one: a corrupt sidecar is
+ * treated as absent so the image still gets approved.
+ */
+export declare function readRunStructure(imagePath: string): Promise<RunStructure | null>;
+/**
+ * Write `image` as the baseline for `storyId`, and the run's structure sidecar
+ * beside it when the store can hold one.
+ *
+ * Throws only if `store.put` does. A sidecar that fails to write is returned
+ * as `structureError`, never thrown: the image is already approved by then,
+ * and structure must never fail a story.
+ */
+export declare function approveCapture(store: BaselineStore, storyId: string, image: Buffer, meta: ApprovalMeta, imagePath: string): Promise<{
+    structureError?: string;
+}>;

package/dist/baseline/approve.js

@@ -0,0 +1,54 @@
+// Promoting a run's capture to a baseline, with its structure sidecar.
+//
+// One helper because there are three approval paths — `jux approve`,
+// `jux init` and the review server behind the Storybook panel — and they
+// disagreed: only `jux approve` kept the sidecar, so every baseline `init`
+// bootstrapped, and every panel approval, silently dropped its structure.
+import { readFile } from 'node:fs/promises';
+import { decodeStructure } from '../capture/structure.js';
+/**
+ * The structure sidecar written beside a run capture (`<x>.webp` →
+ * `<x>.structure.json.gz`), or null when there is none.
+ *
+ * Structure explains a diff, it never gates one: a corrupt sidecar is
+ * treated as absent so the image still gets approved.
+ */
+export async function readRunStructure(imagePath) {
+    const gz = await readFile(imagePath.replace(/\.webp$/, '.structure.json.gz')).catch(() => null);
+    if (!gz)
+        return null;
+    try {
+        const { structureHash } = decodeStructure(gz);
+        return typeof structureHash === 'string' ? { gz, structureHash } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write `image` as the baseline for `storyId`, and the run's structure sidecar
+ * beside it when the store can hold one.
+ *
+ * Throws only if `store.put` does. A sidecar that fails to write is returned
+ * as `structureError`, never thrown: the image is already approved by then,
+ * and structure must never fail a story.
+ */
+export async function approveCapture(store, storyId, image, meta, imagePath) {
+    // A hash in the manifest with nowhere to keep its sidecar would claim a
+    // structure no one can read, so a store without putStructure gets neither.
+    const structure = store.putStructure ? await readRunStructure(imagePath) : null;
+    await store.put(storyId, image, {
+        ...meta,
+        ...(structure ? { structureHash: structure.structureHash } : {}),
+    });
+    if (!structure)
+        return {};
+    try {
+        await store.putStructure(storyId, structure.gz);
+        return {};
+    }
+    catch (err) {
+        return { structureError: err.message };
+    }
+}
+//# sourceMappingURL=approve.js.map

package/dist/baseline/approve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve.js","sourceRoot":"","sources":["../../src/baseline/approve.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,qEAAqE;AACrE,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAQ1D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiB;IACtD,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,CACjF,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;IACF,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,EAAE,aAAa,EAAE,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;QAC9C,OAAO,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAoB,EACpB,OAAe,EACf,KAAa,EACb,IAAkB,EAClB,SAAiB;IAEjB,wEAAwE;IACxE,2EAA2E;IAC3E,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,MAAM,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE;QAC9B,GAAG,IAAI;QACP,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC,CAAC;IACH,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,YAAa,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;QACjD,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,cAAc,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;IACpD,CAAC;AACH,CAAC"}

package/dist/baseline/git-store.d.ts

@@ -9,6 +9,10 @@ export declare class GitBaselineStore implements BaselineStore {
     private readonly manifestPath;
     constructor(opts: GitStoreOptions);
     private imagePath;
+    private structurePath;
+    locate(storyId: string): string;
+    putStructure(storyId: string, gz: Buffer): Promise<void>;
+    getStructure(storyId: string): Promise<Buffer | null>;
     get(storyId: string): Promise<Buffer | null>;
     put(storyId: string, image: Buffer, meta: ApprovalMeta): Promise<void>;
     remove(storyId: string): Promise<void>;

package/dist/baseline/git-store.js

@@ -29,6 +29,24 @@ export class GitBaselineStore {
     imagePath(storyId) {
         return path.join(this.imageDir, `${encodeStoryId(storyId)}.webp`);
     }
+    structurePath(storyId) {
+        return path.join(this.imageDir, `${encodeStoryId(storyId)}.structure.json.gz`);
+    }
+    locate(storyId) {
+        return this.imagePath(storyId);
+    }
+    async putStructure(storyId, gz) {
+        await mkdir(this.imageDir, { recursive: true });
+        await writeFile(this.structurePath(storyId), gz);
+    }
+    async getStructure(storyId) {
+        try {
+            return await readFile(this.structurePath(storyId));
+        }
+        catch {
+            return null;
+        }
+    }
     async get(storyId) {
         try {
             return await readFile(this.imagePath(storyId));
@@ -39,6 +57,9 @@ export class GitBaselineStore {
     }
     async put(storyId, image, meta) {
         await mkdir(this.imageDir, { recursive: true });
+        // A previous baseline's sidecar must not outlive its pixels: a capture
+        // approved without structure would otherwise inherit the old one.
+        await rm(this.structurePath(storyId), { force: true });
         await writeFile(this.imagePath(storyId), image);
         const manifest = await this.readManifest();
         manifest.baselines[storyId] = { ...meta, hash: hashImage(image) };
@@ -46,6 +67,7 @@ export class GitBaselineStore {
     }
     async remove(storyId) {
         await rm(this.imagePath(storyId), { force: true });
+        await rm(this.structurePath(storyId), { force: true });
         const manifest = await this.readManifest();
         delete manifest.baselines[storyId];
         await this.writeManifest(manifest);

package/dist/baseline/git-store.js.map

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

package/dist/browser/acquire.d.ts

@@ -0,0 +1,11 @@
+import { Browser } from './browser.js';
+import type { SpawnFn } from './launch.js';
+export interface AcquireOptions {
+    /** `--chrome <path>`; wins over JUX_CHROME and the caches. */
+    chrome?: string;
+    env?: NodeJS.ProcessEnv;
+    spawn?: SpawnFn;
+    /** PR 2: `--no-daemon`. Accepted now so callers need no change later. */
+    noDaemon?: boolean;
+}
+export declare function acquireBrowser(opts?: AcquireOptions): Promise<Browser>;

package/dist/browser/acquire.js

@@ -0,0 +1,15 @@
+// packages/core/src/browser/acquire.ts
+//
+// The one place that decides where a Browser comes from. Every command and
+// the review server call this; PR 2 adds the warm daemon here and nowhere
+// else, so no caller changes when the policy does.
+import { Browser } from './browser.js';
+import { noBrowserMessage, resolveChrome } from './resolve.js';
+export async function acquireBrowser(opts = {}) {
+    const env = opts.env ?? process.env;
+    const resolved = resolveChrome({ flag: opts.chrome, env });
+    if (!resolved)
+        throw new Error(noBrowserMessage());
+    return Browser.launch({ executablePath: resolved.path, spawn: opts.spawn });
+}
+//# sourceMappingURL=acquire.js.map

package/dist/browser/acquire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/browser/acquire.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,mDAAmD;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAW/D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAuB,EAAE;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3D,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACnD,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AAC9E,CAAC"}

package/dist/browser/browser.d.ts

@@ -0,0 +1,53 @@
+import type { Viewport } from '../types.js';
+import { CdpConnection } from './cdp.js';
+import type { SpawnFn } from './launch.js';
+import { type Page } from './page.js';
+/**
+ * The browser process is gone (killed, crashed, or closed under us). Every
+ * story still queued fails with this one error rather than with N cascading
+ * TargetClosedErrors that each look like a story problem.
+ */
+export declare class BrowserDiedError extends Error {
+    constructor(cause?: unknown);
+}
+export interface ContextOptions {
+    viewport: Viewport;
+    /** `serviceWorkers: 'block'` in Playwright terms: an init script that stubs registration. */
+    blockServiceWorkers?: boolean;
+}
+export declare class BrowserContext {
+    private readonly connection;
+    readonly id: string;
+    private readonly opts;
+    private readonly os;
+    private closed;
+    private readonly pages;
+    constructor(connection: CdpConnection, id: string, opts: ContextOptions, os: NodeJS.Platform);
+    newPage(): Promise<Page>;
+    /** Storage.clearCookies, as Playwright's clearCookies (coreBundle.js L38394). */
+    clearCookies(): Promise<void>;
+    /** Disposing the context closes its targets; their listeners go with them. */
+    close(): Promise<void>;
+}
+export declare class Browser {
+    private readonly connection;
+    private readonly productVersion;
+    private readonly closeFn;
+    private readonly os;
+    private constructor();
+    static launch(opts: {
+        executablePath: string;
+        args?: string[];
+        spawn?: SpawnFn;
+    }): Promise<Browser>;
+    /** PR 2: a connection owned by someone else (the daemon). */
+    static fromConnection(connection: CdpConnection, opts: {
+        version: string;
+        close: () => Promise<void>;
+    }): Browser;
+    /** `151.0.7922.34` — the string Playwright's `browser.version()` returned, so CaptureEnv compares equal. */
+    version(): string;
+    isConnected(): boolean;
+    newContext(opts: ContextOptions): Promise<BrowserContext>;
+    close(): Promise<void>;
+}

package/dist/browser/browser.js

@@ -0,0 +1,122 @@
+// packages/core/src/browser/browser.ts
+//
+// Browser = one CDP connection (pipe now, daemon socket in PR 2).
+// BrowserContext = Target.createBrowserContext, one per pool worker, so
+// concurrently rendering stories never share storage or service workers
+// (pool.ts measured isolation at ~0% cost).
+import { CdpConnection } from './cdp.js';
+import { CdpPage } from './page.js';
+/**
+ * The browser process is gone (killed, crashed, or closed under us). Every
+ * story still queued fails with this one error rather than with N cascading
+ * TargetClosedErrors that each look like a story problem.
+ */
+export class BrowserDiedError extends Error {
+    constructor(cause) {
+        super('jux: the browser died mid-run; the remaining stories were not captured', cause === undefined ? undefined : { cause });
+        this.name = 'BrowserDiedError';
+    }
+}
+export class BrowserContext {
+    connection;
+    id;
+    opts;
+    os;
+    closed = false;
+    pages = new Set();
+    constructor(connection, id, opts, os) {
+        this.connection = connection;
+        this.id = id;
+        this.opts = opts;
+        this.os = os;
+    }
+    async newPage() {
+        const { targetId } = await this.connection.send('Target.createTarget', {
+            url: 'about:blank',
+            browserContextId: this.id,
+        });
+        let page;
+        try {
+            const { sessionId } = await this.connection.send('Target.attachToTarget', { targetId, flatten: true });
+            page = await CdpPage.create(this.connection, targetId, sessionId, {
+                viewport: this.opts.viewport,
+                blockServiceWorkers: this.opts.blockServiceWorkers === true,
+                os: this.os,
+            });
+        }
+        catch (e) {
+            // A target nobody drives is a leak until the context closes; close it now.
+            await this.connection.send('Target.closeTarget', { targetId }).catch(() => { });
+            throw e;
+        }
+        this.pages.add(page);
+        return page;
+    }
+    /** Storage.clearCookies, as Playwright's clearCookies (coreBundle.js L38394). */
+    async clearCookies() {
+        await this.connection.send('Storage.clearCookies', { browserContextId: this.id });
+    }
+    /** Disposing the context closes its targets; their listeners go with them. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const page of this.pages)
+            page.dispose();
+        this.pages.clear();
+        await this.connection
+            .send('Target.disposeBrowserContext', { browserContextId: this.id })
+            .catch(() => { });
+    }
+}
+export class Browser {
+    connection;
+    productVersion;
+    closeFn;
+    os;
+    constructor(connection, productVersion, closeFn, os) {
+        this.connection = connection;
+        this.productVersion = productVersion;
+        this.closeFn = closeFn;
+        this.os = os;
+    }
+    static async launch(opts) {
+        // Lazy: the launcher is the only module that spawns Chrome, and `jux diff`
+        // (which imports core for its pixel code) must never load it. The
+        // no-browser probe in scripts/check-diff.mjs holds that line.
+        const { launchChrome } = await import('./launch.js');
+        const launched = await launchChrome(opts);
+        try {
+            const { product } = await launched.connection.send('Browser.getVersion');
+            return new Browser(launched.connection, stripProduct(product), launched.close, process.platform);
+        }
+        catch (e) {
+            await launched.close();
+            throw e;
+        }
+    }
+    /** PR 2: a connection owned by someone else (the daemon). */
+    static fromConnection(connection, opts) {
+        return new Browser(connection, stripProduct(opts.version), opts.close, process.platform);
+    }
+    /** `151.0.7922.34` — the string Playwright's `browser.version()` returned, so CaptureEnv compares equal. */
+    version() {
+        return this.productVersion;
+    }
+    isConnected() {
+        return !this.connection.closed;
+    }
+    async newContext(opts) {
+        const { browserContextId } = await this.connection.send('Target.createBrowserContext', {
+            disposeOnDetach: true,
+        });
+        return new BrowserContext(this.connection, browserContextId, opts, this.os);
+    }
+    async close() {
+        await this.closeFn();
+    }
+}
+function stripProduct(product) {
+    return product.replace(/^[A-Za-z]+\//, '');
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser/browser.js.map

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

package/dist/browser/cdp.d.ts

@@ -0,0 +1,81 @@
+import type { Transport } from './transport.js';
+export interface RawMessage {
+    id?: number;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+    sessionId?: string;
+}
+export declare const SEND_TIMEOUT_MS = 30000;
+export declare class CdpError extends Error {
+    readonly code: number;
+    constructor(code: number, method: string, message: string);
+}
+export declare class TargetClosedError extends Error {
+    constructor(reason?: string, method?: string);
+}
+export declare class SendTimeoutError extends Error {
+    constructor(method: string, timeout: number);
+}
+type Handler = (params: unknown, sessionId?: string) => void;
+export declare class CdpConnection {
+    private readonly transport;
+    private lastId;
+    private readonly pending;
+    /** key = `${sessionId ?? ''}\n${method}` */
+    private readonly handlers;
+    private readonly closeWaiters;
+    private _closed;
+    private closeReason;
+    onClose: ((reason?: string) => void) | null;
+    /** Every parsed frame, before routing. The PR 2 supervisor proxies from here. */
+    onRaw: ((m: RawMessage) => void) | null;
+    /**
+     * A throwing event handler or onRaw must not escape into the stream's data
+     * event (an uncaught exception would kill the daemon) nor skip the rest of
+     * the chunk. Default: one line on stderr.
+     */
+    onError: (error: unknown, where: 'handler' | 'onRaw') => void;
+    constructor(transport: Transport);
+    get closed(): boolean;
+    get pendingCount(): number;
+    /** Number of distinct (session, method) handler keys; empty sets are pruned. */
+    get handlerKeyCount(): number;
+    /** Total registered handlers, summed over every key; a leak test's yardstick. */
+    get handlerCount(): number;
+    /**
+     * Call `listener` once when the connection closes (at once if it already
+     * has); returns the unsubscribe. Pages use it to fail in-flight work fast
+     * instead of waiting out each send's timeout.
+     */
+    onClosed(listener: (e: Error) => void): () => void;
+    allocateId(): number;
+    /**
+     * Throws TargetClosedError once the connection is closed, so a proxying
+     * caller (the PR 2 supervisor) learns its client message was not delivered
+     * instead of waiting for a reply that cannot come.
+     */
+    sendRaw(message: RawMessage & {
+        id: number;
+        method: string;
+    }): void;
+    send<T = unknown>(method: string, params?: object, sessionId?: string, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    on(method: string, handler: Handler, sessionId?: string): () => void;
+    /**
+     * Without a sessionId this listens on the browser session only, where
+     * session-scoped events never arrive; pass the page's sessionId for page
+     * events.
+     */
+    once<P = unknown>(method: string, sessionId?: string, predicate?: (p: P) => boolean): Promise<P>;
+    close(): void;
+    private dispatch;
+    private runHandlers;
+    private handleClose;
+}
+export {};