@juxtapose/core 0.5.0 → 0.6.0

package/dist/browser/acquire.d.ts

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

package/dist/browser/acquire.js

@@ -2,14 +2,25 @@
 //
 // 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.
+// else, so no caller changes when the policy does (Ruling 3).
 import { Browser } from './browser.js';
-import { noBrowserMessage, resolveChrome } from './resolve.js';
+import { connectWarmBrowser, daemonEnabled, daemonIdleMinutes } from './daemon/client.js';
+import { daemonSupported } from './daemon/state.js';
+import { juxStateDir, 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 });
+    // Ruling 22: no daemon on Windows; CI and the opt-outs get PR 1's path exactly.
+    if (!daemonSupported() || !daemonEnabled(env, opts.noDaemon))
+        return Browser.launch({ executablePath: resolved.path, spawn: opts.spawn });
+    const { browser } = await (opts.connectWarm ?? connectWarmBrowser)({
+        executablePath: resolved.path,
+        stateDir: juxStateDir({ env }),
+        env,
+        idleMinutes: daemonIdleMinutes(env),
+    });
+    return browser;
 }
 //# sourceMappingURL=acquire.js.map

package/dist/browser/acquire.js.map

@@ -1 +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"}
+{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/browser/acquire.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,8DAA8D;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAc5E,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,gFAAgF;IAChF,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC;QAC1D,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9E,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,kBAAkB,CAAC,CAAC;QACjE,cAAc,EAAE,QAAQ,CAAC,IAAI;QAC7B,QAAQ,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;QAC9B,GAAG;QACH,WAAW,EAAE,iBAAiB,CAAC,GAAG,CAAC;KACpC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/browser/browser.d.ts

@@ -1,4 +1,4 @@
-import type { Viewport } from '../types.js';
+import type { Viewport } from './types.js';
 import { CdpConnection } from './cdp.js';
 import type { SpawnFn } from './launch.js';
 import { type Page } from './page.js';

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