@juxtapose/core 0.2.0 → 0.5.0

package/dist/browser/launch.js

@@ -0,0 +1,265 @@
+// packages/core/src/browser/launch.ts
+//
+// Spawn Chrome with the pipe on fds 3/4, as Playwright does (coreBundle.js
+// L39607). Measured 74–91 ms to Browser.getVersion on an M-series Mac, the
+// same as Playwright's launch: the cost is Chrome's, not the driver's.
+//
+// `spawn` is injectable so the no-browser probe (scripts/check-diff.mjs) and
+// tests can assert nothing is launched without patching node:child_process.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { lstat, mkdir, mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { chromeArgs } from '../capture/launch.js';
+import { CdpConnection } from './cdp.js';
+import { PipeTransport } from './transport.js';
+/** How long Browser.close gets, then how long SIGTERM gets, before SIGKILL. */
+const GRACEFUL_CLOSE_MS = 2000;
+const TERM_GRACE_MS = 1000;
+/** After SIGKILL the exit event is imminent; bound the wait so close() cannot hang. */
+const KILL_WAIT_MS = 2000;
+/** Chrome answers Browser.getVersion in ~80 ms; this only bounds a wedged binary. */
+const HANDSHAKE_TIMEOUT_MS = 30_000;
+/** How long a failed launch waits for the exit event and the last of stderr. */
+const FAILURE_WAIT_MS = 2000;
+const STDERR_DRAIN_MS = 300;
+/** A profile of a dead owner is only swept once it is this old. */
+const STALE_PROFILE_MS = 10 * 60_000;
+/** Live launches, so a signal or exit can take every Chrome and profile with it. */
+const live = new Set();
+let handlersInstalled = false;
+/** Kill every live Chrome and remove its profile, synchronously. Exported for tests. */
+export function terminateAll() {
+    for (const l of live) {
+        if (!l.gone) {
+            try {
+                l.proc.kill('SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+        try {
+            rmSync(l.userDataDir, { recursive: true, force: true, maxRetries: 3 });
+        }
+        catch {
+            // best effort: the stale-profile sweep gets it on a later launch
+        }
+    }
+    live.clear();
+}
+const signalHandlers = new Map();
+function installExitHandlers() {
+    if (!handlersInstalled) {
+        handlersInstalled = true;
+        process.on('exit', terminateAll);
+    }
+    for (const sig of ['SIGINT', 'SIGTERM']) {
+        if (signalHandlers.has(sig))
+            continue;
+        const handler = () => {
+            // Detach first: re-raising with our listener attached would loop forever.
+            process.removeListener(sig, handler);
+            signalHandlers.delete(sig);
+            terminateAll();
+            // Only when nobody else listens is dying the right response; a host with
+            // its own handler (a CLI that prints "interrupted") decides for itself.
+            if (process.listenerCount(sig) === 0)
+                process.kill(process.pid, sig);
+        };
+        signalHandlers.set(sig, handler);
+        process.on(sig, handler);
+    }
+}
+const PROFILE_PREFIX = 'jux-chrome-';
+/**
+ * Remove profiles left by a jux that was SIGKILLed or lost power: named
+ * `jux-chrome-<pid>-…`, owner pid dead, untouched for 10 minutes. Anything
+ * else in the directory is not ours to touch.
+ */
+export async function sweepStaleProfiles(dir) {
+    try {
+        for (const name of await readdir(dir)) {
+            const m = /^jux-chrome-(\d+)-/.exec(name);
+            if (!m)
+                continue;
+            try {
+                process.kill(Number(m[1]), 0);
+                continue; // owner alive (EPERM also lands here via the throw below)
+            }
+            catch (e) {
+                if (e.code !== 'ESRCH')
+                    continue;
+            }
+            const full = path.join(dir, name);
+            try {
+                // lstat: a symlink entry is not a directory of ours, whatever it points at.
+                const st = await lstat(full);
+                if (!st.isDirectory() || Date.now() - st.mtimeMs < STALE_PROFILE_MS)
+                    continue;
+                await rm(full, { recursive: true, force: true, maxRetries: 3 });
+            }
+            catch {
+                // raced with another sweeper, or unreadable: leave it
+            }
+        }
+    }
+    catch {
+        // no readable tmpdir: nothing to sweep
+    }
+}
+/**
+ * The per-user directory every profile lives in. A shared tmpdir lets another
+ * user plant `jux-chrome-<dead pid>-x` (or swap one under us) and have our
+ * sweep delete through it, so profiles and the sweep stay inside a directory
+ * only we can write. Verified with lstat, never chmod/chown'd: a dir that is
+ * not ours is refused, not repaired. Windows has no uid; its tmpdir is already
+ * per-user.
+ */
+export async function privateProfileRoot(opts = {}) {
+    const uid = 'uid' in opts ? opts.uid : process.getuid?.();
+    const root = path.join(opts.base ?? tmpdir(), `jux-${uid ?? 'u'}`);
+    const refuse = (why) => new Error(`jux: refusing to use ${root}: ${why}. Remove it (rm -rf ${root}) and run jux again.`);
+    await mkdir(root, { mode: 0o700 }).catch((e) => {
+        if (e.code !== 'EEXIST')
+            throw e;
+    });
+    const st = await lstat(root);
+    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');
+    }
+    return root;
+}
+async function createProfileDir() {
+    const root = await privateProfileRoot();
+    await sweepStaleProfiles(root);
+    return mkdtemp(path.join(root, `${PROFILE_PREFIX}${process.pid}-`));
+}
+export async function launchChrome(opts) {
+    const spawn = opts.spawn ?? nodeSpawn;
+    const userDataDir = await createProfileDir();
+    const args = chromeArgs({ userDataDir, args: opts.args, headless: opts.headless });
+    let proc;
+    try {
+        proc = spawn(opts.executablePath, args, {
+            // stdin/stdout ignored, stderr kept for the "missing shared library"
+            // message on Linux, 3 = Chrome reads, 4 = Chrome writes.
+            stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        await rm(userDataDir, { recursive: true, force: true });
+        throw new Error(`jux: could not launch the browser: ${describeSpawnError(error, opts.executablePath)}`, { cause: error });
+    }
+    const entry = { proc, userDataDir, gone: false };
+    live.add(entry);
+    installExitHandlers();
+    let stderr = '';
+    proc.stderr?.on('data', (d) => {
+        if (stderr.length < 8192)
+            stderr += d.toString();
+    });
+    // One promise for "the process is gone", resolved never rejected, so an
+    // exit after a successful launch is not an unhandled rejection.
+    const exited = new Promise((resolve) => {
+        proc.on('error', (error) => resolve({ code: null, error }));
+        proc.once('exit', (code) => resolve({ code }));
+    });
+    void exited.then(() => {
+        entry.gone = true;
+        live.delete(entry);
+    });
+    const transport = new PipeTransport(proc.stdio[3], proc.stdio[4]);
+    const connection = new CdpConnection(transport);
+    void exited.then(() => transport.close());
+    let stderrClosed = !proc.stderr;
+    proc.stderr?.once('close', () => (stderrClosed = true));
+    // Race the handshake against an early exit (bad binary, missing .so) and a
+    // wedged binary. Any failure ends in one place that kills, waits, cleans up
+    // and explains.
+    const timeoutMs = opts.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
+    let timer;
+    const outcome = await Promise.race([
+        connection.send('Browser.getVersion').then(() => 'ready', () => 'closed'),
+        exited.then(() => 'closed'),
+        new Promise((r) => (timer = setTimeout(() => r('timeout'), timeoutMs))),
+    ]);
+    clearTimeout(timer);
+    if (outcome !== 'ready') {
+        if (outcome === 'timeout' && !entry.gone)
+            proc.kill('SIGKILL');
+        // Ref'd timers here: an async spawn failure (EACCES on the 'error' event)
+        // leaves no child handle and a stderr that never closes, so with unref'd
+        // timers a bare `jux snap --chrome <non-exec>` drained its event loop here
+        // and exited 0 silently, leaking the profile.
+        const result = await Promise.race([exited, sleep(FAILURE_WAIT_MS, { ref: true })]);
+        if (!entry.gone)
+            proc.kill('SIGKILL');
+        if (!stderrClosed)
+            await sleep(STDERR_DRAIN_MS, { ref: true });
+        connection.close();
+        live.delete(entry);
+        await rm(userDataDir, { recursive: true, force: true, maxRetries: 3 });
+        const exe = opts.executablePath;
+        const why = outcome === 'timeout'
+            ? `the browser at ${exe} did not answer within ${timeoutMs} ms and was killed. Reinstall it with \`npx -p @juxtapose/cli jux browser install\`, or point JUX_CHROME at a working Chrome.`
+            : result?.error
+                ? describeSpawnError(result.error, exe)
+                : `the browser at ${exe} exited with code ${result?.code ?? 'unknown'} before it was ready.${describeStderr(stderr)}`;
+        throw new Error(`jux: could not launch the browser: ${why}`);
+    }
+    let closing = null;
+    const close = () => (closing ??= (async () => {
+        if (!connection.closed) {
+            connection.send('Browser.close').catch(() => { });
+            await Promise.race([exited, sleep(GRACEFUL_CLOSE_MS)]);
+        }
+        // Escalate, then wait for the exit so no zombie outlives close().
+        if (!entry.gone) {
+            proc.kill('SIGTERM');
+            await Promise.race([exited, sleep(TERM_GRACE_MS)]);
+        }
+        if (!entry.gone) {
+            proc.kill('SIGKILL');
+            await Promise.race([exited, sleep(KILL_WAIT_MS)]);
+        }
+        connection.close();
+        live.delete(entry);
+        await rm(userDataDir, { recursive: true, force: true });
+    })());
+    return { connection, pid: proc.pid, userDataDir, close };
+}
+/**
+ * Unref'd by default: close() waits on a live child, whose handle already holds
+ * the loop, and must not keep a host alive on its own. Pass `ref` where nothing
+ * else may be holding the loop open.
+ */
+const sleep = (ms, opts = {}) => new Promise((r) => {
+    const t = setTimeout(r, ms);
+    if (!opts.ref)
+        t.unref();
+});
+/** ENOENT / EACCES on spawn: say what to do, not just what the kernel said. */
+function describeSpawnError(error, executablePath) {
+    const code = error.code;
+    if (code === 'ENOENT' || code === 'EACCES') {
+        const what = code === 'ENOENT' ? 'does not exist' : 'is not executable';
+        return `${executablePath} ${what}. Install the pinned browser with \`npx -p @juxtapose/cli jux browser install\`, or point JUX_CHROME at a Chrome you already have.`;
+    }
+    return `${error.message} (${executablePath})`;
+}
+/** Linux: `error while loading shared libraries: libnss3.so` → name the apt line. */
+function describeStderr(stderr) {
+    const m = /error while loading shared libraries: ([^:]+):/.exec(stderr);
+    if (m) {
+        return ` Missing system library ${m[1]}. On Ubuntu 24.04: sudo apt-get install libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 libatspi2.0-0t64 libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcb1 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2`;
+    }
+    return stderr.trim() ? `\n${stderr.trim().split('\n').slice(-3).join('\n')}` : '';
+}
+//# sourceMappingURL=launch.js.map

package/dist/browser/launch.js.map

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

package/dist/browser/page.d.ts

@@ -0,0 +1,125 @@
+import type { Viewport } from '../types.js';
+import { CdpConnection } from './cdp.js';
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+/** The renderer died (OOM, Page.crash, a GPU fault); the page cannot be used again. */
+export declare class PageCrashedError extends Error {
+    constructor();
+}
+/**
+ * The page a platform adapter drives: the public adapter API, exported from
+ * `@juxtapose/core`. Adapters receive it in `showStory`, `settle`,
+ * `switchStory` and `readLiveParams`.
+ *
+ * Stable (semver): `goto`, `url`, `evaluate`, `waitForFunction`,
+ * `waitForSelector`, `addStyleTag`, `setViewportSize`, `screenshot`.
+ * Everything else serves core's own pipeline (snap, structure, the pool) and
+ * may change without a major version.
+ *
+ * Selectors (`waitForSelector`, `screenshot({ mask })`) are CSS, resolved
+ * through open shadow roots; anything else throws synchronously.
+ */
+export interface Page {
+    /** Navigate and resolve on the main frame's `load`; rejects at `timeout` with the URL. */
+    goto(url: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    url(): string;
+    evaluate<R, A = undefined>(fn: string | ((arg: A) => R | Promise<R>), arg?: A, opts?: {
+        timeout?: number;
+    }): Promise<R>;
+    waitForFunction<A = undefined>(fn: (arg: A) => unknown, arg?: A, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForSelector(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    addStyleTag(opts: {
+        content: string;
+    }): Promise<void>;
+    setViewportSize(viewport: Viewport): Promise<void>;
+    screenshot(opts?: {
+        mask?: string[];
+    }): Promise<Buffer>;
+    /**
+     * Raw CDP on this page's session, for DOMSnapshot.
+     * @internal Not part of the adapter API; the protocol surface is Chrome's, not ours.
+     */
+    send<T = unknown>(method: string, params?: object): Promise<T>;
+    /** HTTP status of each main-document response; returns the unsubscribe. */
+    onMainResponse(handler: (status: number) => void): () => void;
+    /** Storage.clearDataForOrigin on this page's session: localStorage, IndexedDB, Cache Storage, service workers. */
+    clearOrigin(origin: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class CdpPage implements Page {
+    private readonly connection;
+    readonly targetId: string;
+    readonly sessionId: string;
+    private currentUrl;
+    private viewport;
+    private closed;
+    /**
+     * Why the page is unusable, once it is. `goneP` rejects with it at that
+     * moment and every send, evaluate and goto races it, so work already in
+     * flight fails at once: Chrome never answers a command on a crashed or
+     * detached session, and a committed navigation whose `load` never comes
+     * would otherwise hold a pool worker for its full timeout.
+     */
+    private goneError;
+    private rejectGone;
+    private readonly goneP;
+    /** Every connection listener this page holds; dispose() removes them all. */
+    private readonly offs;
+    private constructor();
+    /** The spike's init list (spec §Decisions 3), plus Log.enable which Playwright also sends. */
+    static create(connection: CdpConnection, targetId: string, sessionId: string, opts: {
+        viewport: Viewport;
+        blockServiceWorkers: boolean;
+        os: NodeJS.Platform;
+    }): Promise<CdpPage>;
+    send<T = unknown>(method: string, params?: object): Promise<T>;
+    url(): string;
+    onMainResponse(handler: (status: number) => void): () => void;
+    /**
+     * Page.navigate, then the main frame's `load` for the document that
+     * navigation created. The timeout covers the whole thing: Chrome answers
+     * Page.navigate only at commit or failure, so a server that never responds
+     * never replies. A child frame's own `load` must not count (a same-process
+     * iframe fires one for itself), nor may a late `load` from the previous
+     * document: Playwright waits on the new document's loaderId.
+     */
+    goto(url: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    evaluate<R, A = undefined>(fn: string | ((arg: A) => R | Promise<R>), arg?: A, opts?: {
+        timeout?: number;
+    }): Promise<R>;
+    /** Playwright polls on requestAnimationFrame by default (polling: 'raf'). */
+    waitForFunction<A = undefined>(fn: (arg: A) => unknown, arg?: A, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForSelector(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** rAF-poll `predicate(arg)` in the page; true once truthy, false at the in-page cap. */
+    private poll;
+    /** Frame._addStyleTag → addStyleContent, verbatim. */
+    addStyleTag(opts: {
+        content: string;
+    }): Promise<void>;
+    setViewportSize(viewport: Viewport): Promise<void>;
+    /** Screenshotter.screenshotPage: prepare → fonts.ready → mask → getLayoutMetrics → captureScreenshot → cleanup. */
+    screenshot(opts?: {
+        mask?: string[];
+    }): Promise<Buffer>;
+    clearOrigin(origin: string): Promise<void>;
+    close(): Promise<void>;
+    /** Mark closed and drop every listener; idempotent. BrowserContext.close calls it for its pages. */
+    dispose(): void;
+    /** First cause wins: a crash followed by the context closing still reports the crash. */
+    private fail;
+    /** `p`, unless the page goes first. */
+    private guard;
+}