@juxtapose/core 0.4.0 → 0.6.0

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 {};

package/dist/browser/cdp.js

@@ -0,0 +1,230 @@
+// packages/core/src/browser/cdp.ts
+//
+// The whole protocol client: ids out, replies back, events routed by
+// sessionId. Playwright's CRConnection does the same in ~300 lines plus
+// the parts we never use.
+//
+// Every send has a Node-side timeout. Chrome answers Runtime.evaluate only
+// when the script returns, so a story with a synchronous infinite loop would
+// otherwise hang the worker and the run.
+export const SEND_TIMEOUT_MS = 30_000;
+export class CdpError extends Error {
+    code;
+    constructor(code, method, message) {
+        super(`${method}: ${message}`);
+        this.code = code;
+        this.name = 'CdpError';
+    }
+}
+export class TargetClosedError extends Error {
+    constructor(reason = 'browser closed', method) {
+        super(`jux: browser connection closed (${reason})${method ? ` while waiting for ${method}` : ''}`);
+        this.name = 'TargetClosedError';
+    }
+}
+export class SendTimeoutError extends Error {
+    constructor(method, timeout) {
+        super(`jux: ${method} got no reply from the browser within ${timeout} ms`);
+        this.name = 'SendTimeoutError';
+    }
+}
+export class CdpConnection {
+    transport;
+    lastId = 0;
+    pending = new Map();
+    /** key = `${sessionId ?? ''}\n${method}` */
+    handlers = new Map();
+    closeWaiters = new Set();
+    _closed = false;
+    closeReason;
+    onClose = null;
+    /** Every parsed frame, before routing. The PR 2 supervisor proxies from here. */
+    onRaw = 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, where) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`jux: ${where} threw: ${msg}\n`);
+    };
+    constructor(transport) {
+        this.transport = transport;
+        transport.onMessage = (m) => this.dispatch(m);
+        transport.onClose = (reason) => this.handleClose(reason);
+    }
+    get closed() {
+        return this._closed;
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    /** Number of distinct (session, method) handler keys; empty sets are pruned. */
+    get handlerKeyCount() {
+        return this.handlers.size;
+    }
+    /** Total registered handlers, summed over every key; a leak test's yardstick. */
+    get handlerCount() {
+        let n = 0;
+        for (const set of this.handlers.values())
+            n += set.size;
+        return n;
+    }
+    /**
+     * 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) {
+        if (this._closed) {
+            listener(new TargetClosedError(this.closeReason));
+            return () => { };
+        }
+        this.closeWaiters.add(listener);
+        return () => this.closeWaiters.delete(listener);
+    }
+    allocateId() {
+        return ++this.lastId;
+    }
+    /**
+     * 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) {
+        if (this._closed)
+            throw new TargetClosedError(this.closeReason, message.method);
+        this.transport.send(JSON.stringify(message));
+    }
+    send(method, params = {}, sessionId, opts = {}) {
+        if (this._closed)
+            return Promise.reject(new TargetClosedError(this.closeReason, method));
+        const id = this.allocateId();
+        const timeout = opts.timeout ?? SEND_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new SendTimeoutError(method, timeout));
+            }, timeout);
+            timer.unref();
+            this.pending.set(id, {
+                method,
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            try {
+                this.sendRaw(sessionId ? { id, method, params, sessionId } : { id, method, params });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+    }
+    on(method, handler, sessionId) {
+        const key = `${sessionId ?? ''}\n${method}`;
+        let set = this.handlers.get(key);
+        if (!set)
+            this.handlers.set(key, (set = new Set()));
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+            if (set.size === 0 && this.handlers.get(key) === set)
+                this.handlers.delete(key);
+        };
+    }
+    /**
+     * 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(method, sessionId, predicate = () => true) {
+        if (this._closed)
+            return Promise.reject(new TargetClosedError(this.closeReason, method));
+        return new Promise((resolve, reject) => {
+            const onClosed = (e) => {
+                off();
+                reject(e);
+            };
+            const off = this.on(method, (params) => {
+                if (!predicate(params))
+                    return;
+                off();
+                this.closeWaiters.delete(onClosed);
+                resolve(params);
+            }, sessionId);
+            this.closeWaiters.add(onClosed);
+        });
+    }
+    close() {
+        this.transport.close();
+    }
+    dispatch(raw) {
+        let m;
+        try {
+            m = JSON.parse(raw);
+        }
+        catch {
+            return; // Chrome never sends non-JSON frames; nothing to do but ignore.
+        }
+        try {
+            this.onRaw?.(m);
+        }
+        catch (e) {
+            this.onError(e, 'onRaw');
+        }
+        if (m.id !== undefined) {
+            const p = this.pending.get(m.id);
+            if (!p)
+                return; // a raw (proxied) id, or a reply after its timeout
+            this.pending.delete(m.id);
+            clearTimeout(p.timer);
+            if (m.error)
+                p.reject(new CdpError(m.error.code, p.method, m.error.message));
+            else
+                p.resolve(m.result);
+            return;
+        }
+        if (m.method) {
+            const set = this.handlers.get(`${m.sessionId ?? ''}\n${m.method}`);
+            if (set)
+                this.runHandlers(set, m);
+            // Session-less listeners see every event (the browser session's Target.* events).
+            if (m.sessionId) {
+                const all = this.handlers.get(`\n${m.method}`);
+                if (all)
+                    this.runHandlers(all, m);
+            }
+        }
+    }
+    runHandlers(set, m) {
+        for (const h of [...set]) {
+            try {
+                h(m.params, m.sessionId);
+            }
+            catch (e) {
+                this.onError(e, 'handler');
+            }
+        }
+    }
+    handleClose(reason) {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this.closeReason = reason;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new TargetClosedError(reason, p.method));
+        }
+        this.pending.clear();
+        const err = new TargetClosedError(reason);
+        for (const w of [...this.closeWaiters])
+            w(err);
+        this.closeWaiters.clear();
+        this.onClose?.(reason);
+    }
+}
+//# sourceMappingURL=cdp.js.map

package/dist/browser/cdp.js.map

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

package/dist/browser/daemon/client.d.ts

@@ -0,0 +1,145 @@
+import { type ChildProcess } from 'node:child_process';
+import { Browser } from '../browser.js';
+import { type DaemonPaths, type DaemonState } from './state.js';
+export interface SpawnArgs {
+    executablePath: string;
+    args: string[];
+    stateDir: string;
+    key: string;
+    idleMinutes: number;
+}
+export interface WarmOptions {
+    executablePath: string;
+    args?: string[];
+    stateDir: string;
+    /** The caller's environment: the key is computed from it and the daemon runs with it. */
+    env?: NodeJS.ProcessEnv;
+    idleMinutes?: number;
+    /** Test seam: start a daemon for these args with this env. Default: a detached supervisor-main. */
+    spawnDaemon?: (args: SpawnArgs, env: NodeJS.ProcessEnv) => ChildProcess | void;
+    connectTimeoutMs?: number;
+    /** Test seam: see CommandReader. */
+    readCommand?: CommandReader;
+}
+/**
+ * The command line of a pid, '' when no such process exists, null when this
+ * machine gives no way to read it (no /proc and no ps).
+ */
+export type CommandReader = (pid: number) => Promise<string | null>;
+/**
+ * `CI` is the convention; these are the systems that do not set it (GitHub
+ * Actions does, but `CI` can be unset in a step's env; Jenkins sets BUILD_ID).
+ */
+export declare const CI_ENV_VARS: readonly ["CI", "GITHUB_ACTIONS", "JENKINS_URL", "BUILD_ID", "TEAMCITY_VERSION", "BUILDKITE", "GITLAB_CI", "TF_BUILD", "CODEBUILD_BUILD_ID"];
+/** Off with `--no-daemon`, JUX_NO_DAEMON (any truthy value), or any CI marker. */
+export declare function daemonEnabled(env: NodeJS.ProcessEnv, flagNoDaemon?: boolean): boolean;
+/**
+ * JUX_BROWSER_IDLE_MINUTES within [1, 35000], else the default (undefined).
+ * The upper bound is setTimeout's: 100000 minutes overflowed to a 1 ms idle
+ * timer and the daemon quit as soon as its last client left. Infinity used to
+ * pass too, became null in the spawn JSON, and every supervisor exited 1.
+ */
+export declare function daemonIdleMinutes(env: NodeJS.ProcessEnv): number | undefined;
+type StatusOptions = Pick<WarmOptions, 'executablePath' | 'stateDir' | 'args' | 'env' | 'readCommand'>;
+/**
+ * A hash of `entry` and every file it reaches through relative imports. The
+ * supervisor that serves a client is whichever build spawned it; after a
+ * rebuild or an upgrade the supervisor's flags, allowlist or protocol can
+ * differ from this client's, and reusing it would render with the old code.
+ * A missing file hashes as missing (vitest runs the .ts sources, where the
+ * .js entry does not exist).
+ */
+export declare function buildIdentity(entry: string): string;
+/**
+ * `<@juxtapose/core version>+<build hash of the supervisor entry>`. Cached
+ * per process, but rechecked by stat on every call (about ten files): a
+ * Storybook addon or review server that stays up across a `pnpm build` kept
+ * the old key while spawning the new supervisor-main from disk, so it never
+ * shared a daemon with the CLI and ran a mixed build (PR #102 re-review N5).
+ */
+export declare function juxIdentity(entry?: string): string;
+/**
+ * The daemon key for these options. It covers everything a fresh launch
+ * would render with: the binary (path, size, mtime), the pin, the full Chrome
+ * command line jux would launch, the render env and this jux build. Keys that
+ * differ name different sockets, so a daemon from an older jux or other
+ * flags is never reused; it idles out.
+ */
+export declare function daemonKeyFor(opts: Pick<WarmOptions, 'executablePath' | 'args' | 'env'>, jux?: string): string;
+/**
+ * Start a detached supervisor-main with the caller's env: the key was computed
+ * from that env, so Chrome must render with it (TZ, LANG, fonts), not with
+ * whatever env this process happens to have. Detached in its own process
+ * group with stdio ignored: it outlives this jux, and a Ctrl-C to this
+ * terminal must not reach it.
+ *
+ * NODE_OPTIONS is not a render input and is dropped: VS Code's debug
+ * terminal (`--require …/bootloader.js`), `--inspect` or `--cpu-prof` would
+ * otherwise attach to a process that lives for hours, and `--cpu-prof` would
+ * write a profile into the project when it finally exits. The cwd is the
+ * state dir for the same reason: not the project that happened to start it.
+ */
+export declare function spawnSupervisor(args: SpawnArgs, env: NodeJS.ProcessEnv, entry?: string): ChildProcess;
+export declare const defaultReadCommand: CommandReader;
+/**
+ * Remove the files of the daemon `s` describes, and nothing newer. The state
+ * goes only if it still names the same pid and start time: between our read
+ * and this call another client may have spawned a replacement that wrote its
+ * own (the review traced `jux browser stop` deleting a new daemon's files
+ * while the old one's Chrome took 5 s to close, orphaning the new one). The
+ * socket goes only if it is the path that state named and nothing listens on
+ * it, compared by inode so a socket bound meanwhile is left alone.
+ */
+export declare function clearStaleState(paths: DaemonPaths, s: DaemonState): Promise<void>;
+/**
+ * The warm daemon's browser, or a private one if the daemon cannot be had.
+ * Never rejects because of the daemon; a private launch failure rejects as in
+ * PR 1.
+ */
+export declare function connectWarmBrowser(opts: WarmOptions): Promise<{
+    browser: Browser;
+    warm: boolean;
+}>;
+/**
+ * Start (or find) the daemon without a private fallback: `jux browser start`
+ * must not launch and close a whole Chrome just to report that the daemon
+ * could not start.
+ */
+export declare function startDaemon(opts: WarmOptions): Promise<{
+    state: DaemonState;
+} | {
+    error: string;
+}>;
+/** The running daemon for this fingerprint, or null. A dead daemon's files are cleared. */
+export declare function daemonStatus(given: StatusOptions): Promise<DaemonState | null>;
+type ListOptions = Pick<WarmOptions, 'stateDir' | 'readCommand'>;
+/** Every live daemon in `stateDir`, whichever key; dead ones' files are cleared on the way. */
+export declare function listDaemons(opts: ListOptions): Promise<DaemonState[]>;
+/**
+ * What stopping one daemon did: `none` (nothing running, or the state named a
+ * pid that is not ours and nothing listened on its socket), `stopped` (its
+ * pid is gone), `unverified` (a live pid we could not confirm as ours:
+ * nothing is signalled or removed), or `running` (ours, signalled, and still
+ * alive after 2 s).
+ */
+export type StopResult = {
+    outcome: 'none' | 'stopped';
+} | {
+    outcome: 'unverified' | 'running';
+    pid: number;
+    reason: string;
+};
+/** Stop the daemon for this fingerprint only. */
+export declare function stopDaemon(given: StatusOptions): Promise<StopResult>;
+/** One daemon `stopAllDaemons` found, and what stopping it did. */
+export type DaemonStop = {
+    key: string;
+    pid: number;
+} & StopResult;
+/**
+ * Stop every daemon in `stateDir`, whichever key it runs under, each through
+ * the same verification as `stopDaemon`. Entries whose outcome is `none`
+ * (stale files, reused pids) are cleared and left out.
+ */
+export declare function stopAllDaemons(opts: ListOptions): Promise<DaemonStop[]>;
+export {};