@juxtapose/core 0.4.0 → 0.6.0

package/dist/browser/private-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates `dir` 0700 if missing, then checks it with lstat: a real directory
+ * (not a symlink), owned by `uid`, with no group/other write bits. Never
+ * chmod/chown's: a directory we did not create is refused, not repaired.
+ * Without a uid (Windows) only the symlink/directory check applies.
+ */
+export declare function ensurePrivateDir(dir: string, uid: number | undefined, refuse: (why: string) => Error): Promise<void>;

package/dist/browser/private-dir.js

@@ -0,0 +1,24 @@
+// A directory only this user can write, verified rather than assumed. Shared
+// by the Chrome profile root (launch.ts) and the daemon state dir
+// (daemon/state.ts): both hold things another local user must not be able to
+// plant, swap or read through (Ruling 17).
+import { lstat, mkdir } from 'node:fs/promises';
+/**
+ * Creates `dir` 0700 if missing, then checks it with lstat: a real directory
+ * (not a symlink), owned by `uid`, with no group/other write bits. Never
+ * chmod/chown's: a directory we did not create is refused, not repaired.
+ * Without a uid (Windows) only the symlink/directory check applies.
+ */
+export async function ensurePrivateDir(dir, uid, refuse) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const st = await lstat(dir);
+    if (st.isSymbolicLink() || !st.isDirectory())
+        throw refuse('it is not a real directory');
+    if (uid !== undefined) {
+        if (st.uid !== uid)
+            throw refuse('it is owned by another user');
+        if ((st.mode & 0o022) !== 0)
+            throw refuse('it is writable by other users');
+    }
+}
+//# sourceMappingURL=private-dir.js.map

package/dist/browser/private-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-dir.js","sourceRoot":"","sources":["../../src/browser/private-dir.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,kEAAkE;AAClE,6EAA6E;AAC7E,2CAA2C;AAE3C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,GAAuB,EACvB,MAA8B;IAE9B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE;QAC1C,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,IAAI,EAAE,CAAC,GAAG,KAAK,GAAG;YAAE,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;QAChE,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC;YAAE,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/browser/resolve.d.ts

@@ -0,0 +1,31 @@
+import { type ChromePlatform } from './pins.js';
+export interface ResolveOptions {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    homedir?: string;
+    exists?: (p: string) => boolean;
+    isDirectory?: (p: string) => boolean;
+}
+export type ChromeSource = 'flag' | 'env' | 'jux-cache' | 'ms-playwright';
+export interface ResolvedChrome {
+    path: string;
+    source: ChromeSource;
+}
+export declare const INSTALL_MARKER = ".complete";
+export declare const NO_BROWSER_MESSAGE = "jux: no browser. Run `npx -p @juxtapose/cli jux browser install`, or set JUX_CHROME=<path to a Chromium headless shell>.";
+/** The no-browser message, with the platform explanation when there is no build to install. */
+export declare function noBrowserMessage(opts?: ResolveOptions): string;
+export declare function juxCacheDir(opts?: ResolveOptions): string;
+/**
+ * Where the warm-browser daemon keeps its socket, state and lock. Defaults to
+ * the cache dir (so existing setups do not move); JUX_STATE_DIR moves it alone,
+ * e.g. to a short path when the cache dir is too long for a unix socket.
+ */
+export declare function juxStateDir(opts?: ResolveOptions): string;
+export declare function chromeInstallDir(cacheDir: string, version?: string): string;
+/** Mirrors the zip's top-level folder so `extractZip` needs no renaming. */
+export declare function chromeBinaryPath(installDir: string, platform: ChromePlatform): string;
+export declare function msPlaywrightBinaryPath(opts?: ResolveOptions): string;
+export declare function resolveChrome(opts?: ResolveOptions): ResolvedChrome | null;

package/dist/browser/resolve.js

@@ -0,0 +1,126 @@
+// packages/core/src/browser/resolve.ts
+//
+// Where the browser comes from, in order: --chrome, JUX_CHROME, our cache,
+// Playwright's cache. The last one is not a courtesy: it is the same bytes
+// (pins.ts), and most early users already have it, so the upgrade costs them
+// no download.
+import { existsSync, statSync } from 'node:fs';
+import { homedir as osHomedir } from 'node:os';
+import path from 'node:path';
+import { CHROME_VERSION, MS_PLAYWRIGHT_REVISION, chromePlatform, } from './pins.js';
+/** Paths follow the target platform, not the host, so tests can assert win32 strings anywhere. */
+const pathFor = (platform) => platform === 'win32' ? path.win32 : path.posix;
+const isDirectoryOnDisk = (p) => {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+export const INSTALL_MARKER = '.complete';
+export const NO_BROWSER_MESSAGE = 'jux: no browser. Run `npx -p @juxtapose/cli jux browser install`, or set JUX_CHROME=<path to a Chromium headless shell>.';
+/** The no-browser message, with the platform explanation when there is no build to install. */
+export function noBrowserMessage(opts = {}) {
+    try {
+        chromePlatform(opts.platform ?? process.platform, opts.arch ?? process.arch);
+        return NO_BROWSER_MESSAGE;
+    }
+    catch (err) {
+        return err.message;
+    }
+}
+function osCacheDir(platform, env, home) {
+    const p = pathFor(platform);
+    if (platform === 'darwin')
+        return p.join(home, 'Library', 'Caches');
+    if (platform === 'win32')
+        return env.LOCALAPPDATA || p.join(home, 'AppData', 'Local');
+    return env.XDG_CACHE_HOME || p.join(home, '.cache');
+}
+export function juxCacheDir(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const p = pathFor(platform);
+    if (env.JUX_CACHE_DIR)
+        return p.resolve(env.JUX_CACHE_DIR);
+    return p.join(osCacheDir(platform, env, opts.homedir ?? osHomedir()), 'jux');
+}
+/**
+ * Where the warm-browser daemon keeps its socket, state and lock. Defaults to
+ * the cache dir (so existing setups do not move); JUX_STATE_DIR moves it alone,
+ * e.g. to a short path when the cache dir is too long for a unix socket.
+ */
+export function juxStateDir(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.JUX_STATE_DIR)
+        return pathFor(opts.platform ?? process.platform).resolve(env.JUX_STATE_DIR);
+    return juxCacheDir(opts);
+}
+/** A cache dir with a drive letter or backslashes is a Windows path. */
+const platformOfCacheDir = (cacheDir) => /^[A-Za-z]:|\\/.test(cacheDir) ? 'win32' : 'linux';
+export function chromeInstallDir(cacheDir, version = CHROME_VERSION) {
+    return pathFor(platformOfCacheDir(cacheDir)).join(cacheDir, 'chrome-headless-shell', version);
+}
+/** Mirrors the zip's top-level folder so `extractZip` needs no renaming. */
+export function chromeBinaryPath(installDir, platform) {
+    const exe = platform === 'win64' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+    const p = platform === 'win64' ? path.win32 : path.posix;
+    return p.join(installDir, `chrome-headless-shell-${platform}`, exe);
+}
+export function msPlaywrightBinaryPath(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const cft = chromePlatform(platform, opts.arch ?? process.arch);
+    const p = pathFor(platform);
+    const root = env.PLAYWRIGHT_BROWSERS_PATH ||
+        p.join(osCacheDir(platform, env, opts.homedir ?? osHomedir()), 'ms-playwright');
+    return chromeBinaryPath(p.join(root, `chromium_headless_shell-${MS_PLAYWRIGHT_REVISION}`), cft);
+}
+export function resolveChrome(opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    const p = pathFor(platform);
+    const exists = opts.exists ?? existsSync;
+    const isDirectory = opts.isDirectory ?? isDirectoryOnDisk;
+    // Resolved so a daemon or child with another cwd sees the same file; an
+    // existing directory would only fail later at spawn, with a worse message.
+    const explicit = (raw, label) => {
+        const abs = p.resolve(raw);
+        if (!exists(abs))
+            throw new Error(`jux: ${label} does not exist.`);
+        if (isDirectory(abs))
+            throw new Error(`jux: ${label} is a directory, not a browser executable.`);
+        return abs;
+    };
+    if (opts.flag)
+        return { path: explicit(opts.flag, `--chrome ${opts.flag}`), source: 'flag' };
+    // An empty JUX_CHROME (`JUX_CHROME= jux ...`) is unset, not a path.
+    if (env.JUX_CHROME)
+        return {
+            path: explicit(env.JUX_CHROME, `JUX_CHROME=${env.JUX_CHROME}`),
+            source: 'env',
+        };
+    let cft;
+    try {
+        cft = chromePlatform(platform, opts.arch ?? process.arch);
+    }
+    catch {
+        return null;
+    }
+    const installDir = chromeInstallDir(juxCacheDir(opts));
+    const ours = chromeBinaryPath(installDir, cft);
+    if (exists(ours) && exists(p.join(installDir, INSTALL_MARKER)))
+        return { path: ours, source: 'jux-cache' };
+    // PLAYWRIGHT_BROWSERS_PATH=0 is Playwright's "install inside node_modules"
+    // sentinel, not a directory; joining it would probe a relative "0/" path.
+    if (env.PLAYWRIGHT_BROWSERS_PATH === '0')
+        return null;
+    const theirs = msPlaywrightBinaryPath(opts);
+    // Playwright writes INSTALLATION_COMPLETE last, like our marker.
+    const theirMarker = p.join(p.dirname(p.dirname(theirs)), 'INSTALLATION_COMPLETE');
+    if (exists(theirs) && exists(theirMarker))
+        return { path: theirs, source: 'ms-playwright' };
+    return null;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/browser/resolve.js.map

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

package/dist/browser/selectors.d.ts

@@ -0,0 +1,10 @@
+export declare function isCssSelector(selector: string): boolean;
+export declare function assertCssSelector(selector: string): void;
+/** In-page: every match of `selector` in the document and its open shadow roots. */
+export declare const QUERY_ALL_SOURCE = "function (selector) {\n  const out = [];\n  const walk = (root) => {\n    for (const el of root.querySelectorAll(selector)) out.push(el);\n    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);\n    let node = walker.currentNode;\n    while (node) {\n      if (node.shadowRoot) walk(node.shadowRoot);\n      node = walker.nextNode();\n    }\n  };\n  walk(document);\n  return out;\n}";
+/**
+ * `(function (els, a0, a1…) { body })((queryAll)(selector), arg0, arg1…)`
+ * — one builder for every "do X to all matches" evaluate, so the selector
+ * and arguments are JSON-escaped in exactly one place.
+ */
+export declare function queryAllExpression(selector: string, body: string, ...args: unknown[]): string;

package/dist/browser/selectors.js

@@ -0,0 +1,60 @@
+// packages/core/src/browser/selectors.ts
+//
+// Masks, structure.ts's mask marking and waitForSelector resolve selectors
+// in the page. Playwright's locator engine also accepted `text=`, `>>`,
+// `:has-text()` and friends; those are refused up front so a baseline is
+// never captured unmasked because a selector silently matched nothing
+// (spec §Decisions 5; a documented breaking change in the changeset).
+//
+// Open shadow roots are pierced: each root's own matches first, then its
+// shadow trees. Mask boxes are all the same opaque colour, so their order
+// cannot change a pixel; closed roots are invisible to Playwright too.
+const PLAYWRIGHT_ONLY = [
+    /^[a-zA-Z_-]+=/, // text=, css=, xpath=, id=, nth=, _react=, _vue= (engine prefix)
+    /^internal:/,
+    />>/,
+    /:(has-text|text|text-is|text-matches|visible|nth-match|light|above|below|left-of|right-of|near)\(/,
+    /:visible\b/,
+];
+// Quoted strings are attribute values, never syntax: `[title=">>"]` is CSS.
+// Emptying them (quotes kept) leaves `text="x"` and `:has-text("x")` caught.
+const QUOTED = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+export function isCssSelector(selector) {
+    const syntax = selector.replace(QUOTED, '""');
+    return !PLAYWRIGHT_ONLY.some((re) => re.test(syntax));
+}
+export function assertCssSelector(selector) {
+    if (!isCssSelector(selector)) {
+        throw new Error(`jux: selector '${selector}' is not a CSS selector`);
+    }
+}
+/** In-page: every match of `selector` in the document and its open shadow roots. */
+export const QUERY_ALL_SOURCE = `function (selector) {
+  const out = [];
+  const walk = (root) => {
+    for (const el of root.querySelectorAll(selector)) out.push(el);
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+    let node = walker.currentNode;
+    while (node) {
+      if (node.shadowRoot) walk(node.shadowRoot);
+      node = walker.nextNode();
+    }
+  };
+  walk(document);
+  return out;
+}`;
+/**
+ * `(function (els, a0, a1…) { body })((queryAll)(selector), arg0, arg1…)`
+ * — one builder for every "do X to all matches" evaluate, so the selector
+ * and arguments are JSON-escaped in exactly one place.
+ */
+export function queryAllExpression(selector, body, ...args) {
+    const names = args.map((_, i) => `a${i}`);
+    const params = ['els', ...names].join(', ');
+    const values = [
+        `(${QUERY_ALL_SOURCE})(${JSON.stringify(selector)})`,
+        ...args.map((a) => JSON.stringify(a)),
+    ].join(', ');
+    return `(function (${params}) { ${body} })(${values})`;
+}
+//# sourceMappingURL=selectors.js.map

package/dist/browser/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","sourceRoot":"","sources":["../../src/browser/selectors.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,sEAAsE;AACtE,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,uEAAuE;AAEvE,MAAM,eAAe,GAAG;IACtB,eAAe,EAAE,iEAAiE;IAClF,YAAY;IACZ,IAAI;IACJ,mGAAmG;IACnG,YAAY;CACb,CAAC;AAEF,4EAA4E;AAC5E,6EAA6E;AAC7E,MAAM,MAAM,GAAG,sCAAsC,CAAC;AAEtD,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9C,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,yBAAyB,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;EAa9B,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,IAAY,EACZ,GAAG,IAAe;IAElB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG;QACb,IAAI,gBAAgB,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG;QACpD,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;KACtC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,cAAc,MAAM,OAAO,IAAI,OAAO,MAAM,GAAG,CAAC;AACzD,CAAC"}

package/dist/browser/transport.d.ts

@@ -0,0 +1,51 @@
+import type net from 'node:net';
+export interface Transport {
+    send(message: string): void;
+    onMessage: ((message: string) => void) | null;
+    onClose: ((reason?: string) => void) | null;
+    close(): void;
+}
+/** A frame grew past the framer's cap before its NUL arrived. */
+export declare class FrameTooLargeError extends Error {
+    constructor(limit: number);
+}
+export declare class NullFramer {
+    private readonly maxFrameChars;
+    private parts;
+    private partsChars;
+    private readonly decoder;
+    /**
+     * `maxFrameChars` bounds one frame. Chrome's pipe is trusted and uncapped;
+     * the supervisor caps its clients so one that never sends a NUL cannot grow
+     * the daemon's memory without bound. Past the cap, push() throws.
+     */
+    constructor(maxFrameChars?: number);
+    push(chunk: Buffer | string, onFrame: (frame: string) => void): void;
+}
+/** Framing, close-once and callback plumbing shared by both transports. */
+export declare abstract class FramedTransport implements Transport {
+    onMessage: ((message: string) => void) | null;
+    onClose: ((reason?: string) => void) | null;
+    private readonly framer;
+    private closed;
+    protected abstract write(data: string): void;
+    protected abstract destroy(): void;
+    protected feed(chunk: Buffer | string): void;
+    send(message: string): void;
+    close(): void;
+    protected emitClose(reason: string): void;
+}
+export declare class PipeTransport extends FramedTransport {
+    private readonly writable;
+    private readonly readable;
+    constructor(writable: NodeJS.WritableStream, readable: NodeJS.ReadableStream);
+    private readonly onData;
+    protected write(data: string): void;
+    protected destroy(): void;
+}
+export declare class SocketTransport extends FramedTransport {
+    private readonly socket;
+    constructor(socket: net.Socket);
+    protected write(data: string): void;
+    protected destroy(): void;
+}

package/dist/browser/transport.js

@@ -0,0 +1,124 @@
+// packages/core/src/browser/transport.ts
+//
+// Two byte pipes, one framing. Chrome's --remote-debugging-pipe speaks
+// NUL-terminated JSON on fds 3 (in) and 4 (out); the warm-browser supervisor
+// (PR 2) speaks the same framing over a local socket so one CdpConnection
+// serves both.
+import { StringDecoder } from 'node:string_decoder';
+/** A frame grew past the framer's cap before its NUL arrived. */
+export class FrameTooLargeError extends Error {
+    constructor(limit) {
+        super(`jux: a frame exceeded ${limit} characters`);
+        this.name = 'FrameTooLargeError';
+    }
+}
+export class NullFramer {
+    maxFrameChars;
+    // Pieces of the frame in progress. Joined once when its NUL arrives and only
+    // the new chunk is scanned: re-slicing one growing string made a 20 MB frame
+    // in 64 KB chunks cost 339 ms (40 MB: 1.5 s), quadratic in frame size.
+    parts = [];
+    partsChars = 0;
+    // Chunk boundaries can fall inside a multi-byte UTF-8 character; a plain
+    // toString() per chunk would corrupt it into U+FFFD.
+    decoder = new StringDecoder('utf8');
+    /**
+     * `maxFrameChars` bounds one frame. Chrome's pipe is trusted and uncapped;
+     * the supervisor caps its clients so one that never sends a NUL cannot grow
+     * the daemon's memory without bound. Past the cap, push() throws.
+     */
+    constructor(maxFrameChars = Infinity) {
+        this.maxFrameChars = maxFrameChars;
+    }
+    push(chunk, onFrame) {
+        const text = typeof chunk === 'string' ? chunk : this.decoder.write(chunk);
+        let start = 0;
+        let end;
+        while ((end = text.indexOf('\0', start)) >= 0) {
+            this.parts.push(text.slice(start, end));
+            this.partsChars += end - start;
+            if (this.partsChars > this.maxFrameChars)
+                throw new FrameTooLargeError(this.maxFrameChars);
+            const frame = this.parts.length === 1 ? this.parts[0] : this.parts.join('');
+            this.parts = [];
+            this.partsChars = 0;
+            start = end + 1;
+            onFrame(frame);
+        }
+        if (start < text.length) {
+            this.parts.push(text.slice(start));
+            this.partsChars += text.length - start;
+            if (this.partsChars > this.maxFrameChars)
+                throw new FrameTooLargeError(this.maxFrameChars);
+        }
+    }
+}
+/** Framing, close-once and callback plumbing shared by both transports. */
+export class FramedTransport {
+    onMessage = null;
+    onClose = null;
+    framer = new NullFramer();
+    closed = false;
+    feed(chunk) {
+        this.framer.push(chunk, (f) => this.onMessage?.(f));
+    }
+    // Outgoing writes are unbounded on purpose: CDP commands are small and the
+    // driver awaits replies, so the write queue stays short. The PR 2 supervisor
+    // proxies arbitrary client traffic and must honor write() back-pressure
+    // (drain) itself before it forwards large payloads.
+    send(message) {
+        if (this.closed)
+            return;
+        this.write(message + '\0');
+    }
+    close() {
+        this.destroy();
+        this.emitClose('closed');
+    }
+    emitClose(reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onClose?.(reason);
+    }
+}
+export class PipeTransport extends FramedTransport {
+    writable;
+    readable;
+    constructor(writable, readable) {
+        super();
+        this.writable = writable;
+        this.readable = readable;
+        readable.on('data', this.onData);
+        readable.on('close', () => this.emitClose('pipe closed'));
+        readable.on('error', (e) => this.emitClose(e.message));
+        writable.on('error', (e) => this.emitClose(e.message));
+    }
+    onData = (chunk) => this.feed(chunk);
+    write(data) {
+        this.writable.write(data);
+    }
+    destroy() {
+        // The process owns the fds (launch.ts closes them with the process); we
+        // only stop listening so a closed transport delivers nothing more.
+        this.readable.removeListener('data', this.onData);
+    }
+}
+export class SocketTransport extends FramedTransport {
+    socket;
+    constructor(socket) {
+        super();
+        this.socket = socket;
+        socket.setNoDelay(true);
+        socket.on('data', (chunk) => this.feed(chunk));
+        socket.on('close', () => this.emitClose('socket closed'));
+        socket.on('error', (e) => this.emitClose(e.message));
+    }
+    write(data) {
+        this.socket.write(data);
+    }
+    destroy() {
+        this.socket.destroy();
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/browser/transport.js.map

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

package/dist/browser/types.d.ts

@@ -0,0 +1,4 @@
+export interface Viewport {
+    width: number;
+    height: number;
+}

package/dist/browser/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/browser/types.js.map

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

package/dist/browser/zip.d.ts

@@ -0,0 +1,27 @@
+export interface ZipEntry {
+    name: string;
+    /** POSIX mode from the external attributes (0 when the zip has none). */
+    mode: number;
+    isDirectory: boolean;
+    data: Buffer;
+}
+export interface ZipLimits {
+    maxEntryBytes?: number;
+    maxTotalBytes?: number;
+}
+export declare const MAX_ENTRY_BYTES: number;
+export declare const MAX_TOTAL_BYTES: number;
+export declare function readZip(buf: Buffer, limits?: ZipLimits): ZipEntry[];
+export declare function extractZip(buf: Buffer, dir: string, limits?: ZipLimits): Promise<string[]>;
+export interface InstallOptions extends ZipLimits {
+    /** File written (inside the temp dir, before the swap) so a completed install is always marked. */
+    marker?: string;
+}
+/**
+ * Extract into a sibling temp dir, then swap it into `finalDir`, so a crash
+ * mid-extract never leaves a half-written browser at the path resolve reads.
+ * Any existing `finalDir` (dir, file or symlink) is renamed aside first and
+ * removed after, so there is no window with nothing in place. If a concurrent
+ * installer wins the final rename, its target is complete and ours is dropped.
+ */
+export declare function installZip(buf: Buffer, finalDir: string, opts?: InstallOptions): Promise<string[]>;