@povio/lightning-panda 0.0.0-stage → 0.0.17

package/dist/screenshots.d.ts

@@ -0,0 +1,35 @@
+import type { ScreenshotStep } from './steps.js';
+/** Write new baselines instead of comparing (`LP_UPDATE_SNAPSHOTS=1`, or `bun test --update-snapshots` / `-u`). */
+export declare const updateMode: () => boolean;
+export type ScreenshotResult = {
+    name: string;
+    pass: boolean;
+    /** Passed on the display-list hash: no raster, no pixel compare. */
+    hashHit: boolean;
+    /** No baseline was compared: the render was written as the baseline. */
+    recorded: boolean;
+    diffPixels: number;
+    sceneHash: string;
+    width: number;
+    height: number;
+    /** Browser-side timings, ms. */
+    ms: Record<string, number>;
+    /** The written baseline (recorded) or the images written on a mismatch. */
+    files?: {
+        baseline?: string;
+        actual?: string;
+        diff?: string;
+    };
+};
+export declare class ScreenshotMismatchError extends Error {
+    readonly result: ScreenshotResult;
+    constructor(message: string, result: ScreenshotResult);
+}
+/** A baseline as this connection last received it, by wire name. */
+export type SentBaselines = Map<string, string>;
+/** Fills `step.wire` from disk. */
+export declare function prepare(step: ScreenshotStep, sent: SentBaselines): void;
+/** A step's result from a successful run: writes recorded baselines. */
+export declare function settle(step: ScreenshotStep, r: any): ScreenshotResult;
+/** A failed run's `error.data` for this step: writes the actual image and the diff. */
+export declare function mismatch(step: ScreenshotStep, data: any, message: string): ScreenshotMismatchError;

package/dist/steps.d.ts

@@ -0,0 +1,372 @@
+export type TextMatch = string | RegExp;
+type Pattern = string | {
+    regex: string;
+    flags?: string;
+};
+/** The wire form of a locator (see `crates/lp-cdp/src/engine/driver.rs`). */
+export type LocatorSpec = {
+    css?: string;
+    testId?: string;
+    testIdAttribute?: string;
+    text?: Pattern;
+    role?: string;
+    name?: Pattern;
+    label?: Pattern;
+    placeholder?: Pattern;
+    exact?: boolean;
+    within?: LocatorSpec;
+    filter?: {
+        visible?: boolean;
+        hasText?: Pattern;
+        hasNotText?: Pattern;
+        has?: LocatorSpec;
+        hasNot?: LocatorSpec;
+    };
+    nth?: number;
+    /** Search inside the document of the `<iframe>` this locator matches (in the parent document). */
+    frame?: LocatorSpec;
+};
+export type Step = Record<string, unknown>;
+type Exact = {
+    exact?: boolean;
+};
+/** Anything that becomes one step of a run. */
+export interface StepLike {
+    toStep(): Step;
+}
+export type ActOptions = {
+    settle?: boolean;
+    timeout?: number;
+};
+/**
+ * Pointer options of `click`, `dblclick`, `hover` and `wheel` (engine 0.0.10):
+ * `button` (left), `position` relative to the element's top-left corner
+ * (its center), `force` skips the actionability checks.
+ */
+export type PointerOptions = ActOptions & {
+    button?: 'left' | 'right' | 'middle';
+    position?: {
+        x: number;
+        y: number;
+    };
+    force?: boolean;
+};
+/** A file for `upload`: inline contents (`text` or `base64`) and an optional type. */
+export type UploadFile = {
+    name: string;
+    text?: string;
+    base64?: string;
+    mimeType?: string;
+};
+export type ReadWhat = 'text' | 'value' | 'count' | 'visible' | 'box' | 'css' | 'name' | 'focused' | 'enabled';
+export declare class Locator {
+    readonly spec: LocatorSpec;
+    constructor(spec: LocatorSpec);
+    private with;
+    visible(visible?: boolean): Locator;
+    hasText(text: TextMatch): Locator;
+    hasNotText(text: TextMatch): Locator;
+    has(inner: Locator): Locator;
+    hasNot(inner: Locator): Locator;
+    nth(index: number): Locator;
+    first(): Locator;
+    last(): Locator;
+    /** `spec` scoped to this locator; a `frame` stays on the outermost locator. */
+    private inner;
+    locator(css: string): Locator;
+    role(role: string, name?: TextMatch, opts?: Exact): Locator;
+    button(name?: TextMatch, opts?: Exact): Locator;
+    link(name?: TextMatch, opts?: Exact): Locator;
+    textbox(name?: TextMatch, opts?: Exact): Locator;
+    text(text: TextMatch, opts?: Exact): Locator;
+    label(text: TextMatch, opts?: Exact): Locator;
+    placeholder(text: TextMatch, opts?: Exact): Locator;
+    testId(id: string): Locator;
+    /**
+     * Locators inside the document of the `<iframe>` this locator matches:
+     * `css('#editor').frame().button('Bold')` (Playwright's `frameLocator`).
+     */
+    frame(): FrameScope;
+    /** This locator, searched in the document of the `<iframe>` `frame` matches. */
+    inFrame(frame: Locator): Locator;
+    click(opts?: PointerOptions): StepLike;
+    /** Two clicks at the center (the second with click count 2). */
+    dblclick(opts?: PointerOptions): StepLike;
+    /** Moves the pointer to the element (tooltips, hover toolbars). */
+    hover(opts?: PointerOptions): StepLike;
+    fill(value: string, opts?: ActOptions): StepLike;
+    /** Focuses, then one key press per character (Playwright's `pressSequentially`). */
+    type(text: string, opts?: ActOptions): StepLike;
+    press(key: string, opts?: ActOptions): StepLike;
+    check(opts?: ActOptions): StepLike;
+    uncheck(opts?: ActOptions): StepLike;
+    focus(): StepLike;
+    blur(): StepLike;
+    /**
+     * Sets the files of an `<input type=file>`: inline files, or a path (several:
+     * one per line) on the machine running Lightningpanda.
+     */
+    upload(files: UploadFile[] | string, opts?: ActOptions): StepLike;
+    dropFiles(files: UploadFile[] | string, opts?: ActOptions): StepLike;
+    /** Drags the element onto `to`: native drag and drop when it is a drag source, else a pointer drag. */
+    drag(to: Locator, opts?: ActOptions): StepLike;
+    /** Scrolls with the mouse wheel over the element (engine 0.0.10). */
+    wheel(deltaX: number, deltaY: number, opts?: ActOptions): StepLike;
+    /** Compares this element's box with the baseline `name` (see `matchScreenshot`). */
+    matchScreenshot(name: string, opts?: ScreenshotOptions): ScreenshotStep;
+    /**
+     * Reads a value into the run's `values[as]`: `read('n', 'css', 'color')`
+     * for a computed style property, `'name'` for the accessible name.
+     */
+    read(as: string, what?: ReadWhat, property?: string): StepLike;
+}
+/** Locators inside an `<iframe>`'s document (`loc.frame()`). */
+export declare class FrameScope {
+    private frameLocator;
+    constructor(frameLocator: Locator);
+    locator(css: string): Locator;
+    role(role: string, name?: TextMatch, opts?: Exact): Locator;
+    button(name?: TextMatch, opts?: Exact): Locator;
+    link(name?: TextMatch, opts?: Exact): Locator;
+    textbox(name?: TextMatch, opts?: Exact): Locator;
+    text(text: TextMatch, opts?: Exact): Locator;
+    label(text: TextMatch, opts?: Exact): Locator;
+    placeholder(text: TextMatch, opts?: Exact): Locator;
+    testId(id: string): Locator;
+    /** A nested `<iframe>` inside this one. */
+    frame(inner: Locator): FrameScope;
+}
+export declare const css: (selector: string) => Locator;
+export declare const testId: (id: string, attribute?: string) => Locator;
+export declare const text: (t: TextMatch, opts?: Exact) => Locator;
+export declare const label: (t: TextMatch, opts?: Exact) => Locator;
+export declare const placeholder: (t: TextMatch, opts?: Exact) => Locator;
+export declare const role: (r: string, name?: TextMatch, opts?: Exact) => Locator;
+export declare const button: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const link: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const dialog: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const heading: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const textbox: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const checkbox: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const combobox: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const option: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const row: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const cell: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const tab: (name?: TextMatch, opts?: Exact) => Locator;
+export declare const menuitem: (name?: TextMatch, opts?: Exact) => Locator;
+/** Locators inside the `<iframe>` `frame` matches: `inFrame(css('#editor')).button('Bold')`. */
+export declare const inFrame: (frame: Locator) => FrameScope;
+type CheckOpts = {
+    timeout?: number;
+};
+declare class Check {
+    private loc;
+    private negate;
+    constructor(loc: Locator, negate?: boolean);
+    get not(): Check;
+    private step;
+    visible(opts?: CheckOpts): StepLike;
+    hidden(opts?: CheckOpts): StepLike;
+    text(expected: string, opts?: CheckOpts): StepLike;
+    containsText(expected: string, opts?: CheckOpts): StepLike;
+    value(expected: string, opts?: CheckOpts): StepLike;
+    count(expected: number, opts?: CheckOpts): StepLike;
+    checked(expected?: boolean, opts?: CheckOpts): StepLike;
+    /** A computed style property: `check(button('Save')).css('background-color', 'rgb(1, 2, 3)')`. */
+    css(property: string, expected: string, opts?: CheckOpts): StepLike;
+    /** The element is the document's focused element. */
+    focused(expected?: boolean, opts?: CheckOpts): StepLike;
+    /** The accessible name (exact after whitespace normalization). */
+    name(expected: string, opts?: CheckOpts): StepLike;
+    enabled(expected?: boolean, opts?: CheckOpts): StepLike;
+    disabled(opts?: CheckOpts): StepLike;
+}
+declare class RequestCheck implements StepLike {
+    private m;
+    constructor(m: Record<string, unknown>);
+    /** One status, or any of several (`[200, 304]`). */
+    status(status: number | number[]): RequestCheck;
+    count(count: number): RequestCheck;
+    /** The request body contains (or matches) `body` (engine 0.0.10). */
+    body(body: TextMatch): RequestCheck;
+    /** The request body is a JSON object with exactly these top-level keys (engine 0.0.10). */
+    bodyKeys(keys: string[]): RequestCheck;
+    /** Request headers (case-insensitive names) whose values contain (or match) these (engine 0.0.10). */
+    headers(headers: Record<string, TextMatch>): RequestCheck;
+    /**
+     * `started` also counts requests still in flight (`count` included);
+     * `finished` (the default) only those with a response or an error (engine 0.0.10).
+     */
+    state(state: 'started' | 'finished'): RequestCheck;
+    /** Include prior runs of this page only; batch scope is the default. */
+    scope(scope: 'batch' | 'context'): RequestCheck;
+    timeout(timeout: number): RequestCheck;
+    toStep(): Step;
+}
+/**
+ * `check(locator).visible()`, `.text("…")`, `.count(n)`, `.not.visible()`;
+ * `check.request("POST", "/path").status(200)` checks the run's request log
+ * (`path` is exact, a RegExp tests the full URL).
+ */
+export declare const check: ((loc: Locator) => Check) & {
+    request: (method: string, path: string | RegExp) => RequestCheck;
+};
+export declare const goto: (url: string, waitUntil?: "load" | "domcontentloaded") => StepLike;
+/**
+ * Same-document navigation (pushState + popstate), as a client-side router
+ * sees a link. Settles on the requests it starts unless `settle: false`.
+ */
+export declare const route: (url: string, opts?: ActOptions) => StepLike;
+/**
+ * Evaluates an expression in the page; its JSON value lands in `values[as]`.
+ * A returned promise is awaited (within `timeout`); a rejection fails the step.
+ */
+export declare const evaluate: (expression: string, as?: string, opts?: CheckOpts) => StepLike;
+/**
+ * Waits for the current document's `load`. On a page taken from a pool while
+ * still booting (`lp.page()` adds it), it waits for the profile URL's
+ * navigation to commit and load, never for the `about:blank` before it.
+ */
+export declare const loaded: (opts?: CheckOpts) => StepLike;
+/**
+ * Waits until the page is quiet: no queued task, request in flight, timeout due
+ * within 50 ms, pending animation frame or unfinished navigation. Never fails;
+ * when `timeout` passes first its result has `settled: false` and `pending`.
+ */
+export declare const idle: (opts?: {
+    timeout?: number;
+}) => StepLike;
+/** Reloads the current document and waits for its `load`. */
+export declare const reload: (opts?: CheckOpts) => StepLike;
+/** Waits until the page URL contains (or matches) `url` (Playwright's `waitForURL`). */
+export declare const waitForUrl: (url: TextMatch, opts?: CheckOpts) => StepLike;
+export type MockOptions = {
+    method?: string;
+    status?: number;
+    /** Serialized as the body (content type `application/json`). */
+    json?: unknown;
+    body?: string;
+    contentType?: string;
+    headers?: Record<string, string>;
+    /** Milliseconds before the response (loading states). */
+    delay?: number;
+    /** Fail the request instead, with a `Network.ErrorReason` such as `Failed` or `ConnectionRefused`. */
+    abort?: string;
+    /** Answer only the first n matching requests. */
+    times?: number;
+    /** Let matching requests reach the network unchanged (an exception to a broader mock; engine 0.0.10). */
+    passthrough?: boolean;
+    /** Hold matching requests under this name until a `release(name)` step (engine 0.0.10). */
+    hold?: string;
+    /** Let the request reach the server, then rewrite the fields given of its response (engine 0.0.10). */
+    patch?: {
+        status?: number;
+        headers?: Record<string, string>;
+        json?: unknown;
+        body?: string;
+    };
+};
+/**
+ * Answers requests of this page's context whose URL contains `url` (or
+ * matches the RegExp) with the given response (Playwright's `page.route` +
+ * `fulfill`): `mock('/api/items', { json: [] })`.
+ */
+export declare const mock: (url: TextMatch, opts?: MockOptions) => StepLike;
+/** Removes the mocks matching `url` (all of them without one). */
+export declare const unmock: (url?: TextMatch) => StepLike;
+/** Lets the requests held by `mock(url, { hold: name })` go on (engine 0.0.10). */
+export declare const release: (hold: string) => StepLike;
+/** Resizes the viewport mid-test; layout and `resize` listeners see the new size (engine 0.0.10). */
+export declare const viewport: (width: number, height: number) => StepLike;
+export type MediaOptions = {
+    colorScheme: 'light' | 'dark' | 'no-preference';
+    reducedMotion?: 'reduce' | 'no-preference';
+    /** `screen` or `print`. */
+    media?: string;
+};
+/** Emulates media features (`prefers-color-scheme` and friends) (engine 0.0.10). */
+export declare const media: (opts: MediaOptions) => StepLike;
+/** Reads this page's native initiated-download count without consuming download records. */
+export declare const downloadCount: (as: string) => StepLike;
+/**
+ * Waits for the next download the page starts during the run; its
+ * `{ url, filename, text, ... }` lands in `values[as]`, and the file in
+ * `saveTo` (a directory) when given.
+ */
+export declare const download: (opts?: {
+    saveTo?: string;
+    as?: string;
+    timeout?: number;
+}) => StepLike;
+/**
+ * The following steps drive another page of the context (engine 0.0.10):
+ * the `as` name of an earlier `popup(as)`, a target id, or `'main'` for the
+ * page the run started on. Add `loaded()` or `waitForUrl()` after switching
+ * to a fresh popup.
+ */
+export declare const switchTo: (target: string) => StepLike;
+/** Waits for the next popup the page opens during the run; its target id lands in `values[as]`. */
+export declare const popup: (as?: string, opts?: CheckOpts) => StepLike;
+export type MouseAction = 'click' | 'dblclick' | 'move' | 'down' | 'up' | 'wheel';
+export type MouseOptions = {
+    /** Viewport point; required for `click`, `dblclick` and `move`, else the pointer stays where it is. */
+    x?: number;
+    y?: number;
+    button?: 'left' | 'right' | 'middle';
+    /** `wheel`: scroll deltas. */
+    deltaX?: number;
+    deltaY?: number;
+    /** `move`: intermediate `mousemove` events. */
+    steps?: number;
+    settle?: boolean;
+    timeout?: number;
+};
+/** A raw mouse event at viewport coordinates (engine 0.0.10): `mouse('click', { x: 10, y: 20 })`. */
+export declare const mouse: (action: MouseAction, opts?: MouseOptions) => StepLike;
+/** Mouse wheel over an element (engine 0.0.10). */
+export declare const wheel: (loc: Locator, deltaX: number, deltaY: number, opts?: ActOptions) => StepLike;
+export type ScreenshotOptions = {
+    /** 0-1: how far a pixel's channels may differ and still match (default 0: exact). */
+    threshold?: number;
+    /** Differing pixels allowed (default 0). */
+    maxDiffPixels?: number;
+    /** Differing pixels allowed as a fraction of the image. */
+    maxDiffPixelRatio?: number;
+    /** A rectangle of the document, CSS px. */
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** The whole document, not only the viewport. */
+    fullPage?: boolean;
+    /** Where baselines live (default: `__screenshots__` beside the test file). */
+    dir?: string;
+    timeout?: number;
+};
+/**
+ * A `matchScreenshot` step: the page renders in the browser and is compared
+ * there with the baseline `<dir>/<name>.png`. `page.run` reads the baseline
+ * (sent once per connection), writes it when missing or in update mode, and
+ * writes `<name>.actual.png` and `<name>.diff.png` on a mismatch.
+ */
+export declare class ScreenshotStep implements StepLike {
+    readonly name: string;
+    readonly opts: ScreenshotOptions & {
+        locator?: LocatorSpec;
+    };
+    /** Directory of the test file that built the step. */
+    readonly testDir: string;
+    /** Baseline fields `page.run` adds (`baseline`, `sceneHash`, `update`). */
+    wire: Record<string, unknown>;
+    constructor(name: string, opts: ScreenshotOptions & {
+        locator?: LocatorSpec;
+    }, 
+    /** Directory of the test file that built the step. */
+    testDir: string);
+    toStep(): Step;
+}
+/** Compares the viewport (or `clip`, or `fullPage`) with the baseline `name`. */
+export declare const matchScreenshot: (name: string, opts?: ScreenshotOptions) => ScreenshotStep;
+export {};

package/native/darwin-arm64/lightningpanda

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/native/darwin-arm64/lightningpanda
+size: 35434864 bytes
+sha256: 1239cb423a30531603b31a780234232c28f4d0ec71c1366de2ffa323dbb314e7

package/native/darwin-x64/lightningpanda

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/native/darwin-x64/lightningpanda
+size: 37847744 bytes
+sha256: 2f4e69371305c4fdebc8763f65574113691006d8551c3fde85c519bc33864640

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@povio/lightning-panda",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.17",
+  "description": "Lightningpanda headless browser and typed E2E testing API",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/povio/lightningpanda.git",
+    "directory": "packages/lightning-panda"
+  },
+  "engines": { "node": ">=22" },
+  "publishConfig": { "access": "public" },
+  "bin": { "lightningpanda": "./dist/cli.js" },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LLM.md",
+    "native",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts src/cli.ts --outdir dist --target node --format esm && tsc -p tsconfig.json",
+    "prepack": "bun run build && node ../../scripts/npm/prepare-package.mjs",
+    "test:package": "bun test test/binary.test.ts && node --test ../../scripts/npm/release.test.mjs",
+    "test": "bun test ./test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/binary.ts

@@ -0,0 +1,21 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Shared by the CLI and launch(); never fall back to our own CLI on PATH. */
+export function resolveBinary({
+  platform = process.platform as string,
+  arch = process.arch as string,
+  root = fileURLToPath(new URL('../', import.meta.url)),
+  env = process.env,
+}: { platform?: string; arch?: string; root?: string; env?: NodeJS.ProcessEnv } = {}): string {
+  if (env.LIGHTNINGPANDA_BIN) return env.LIGHTNINGPANDA_BIN;
+  const bundled = join(root, 'native', `${platform}-${arch}`, 'lightningpanda');
+  if (statSync(bundled, { throwIfNoEntry: false })?.isFile()) return bundled;
+  const sibling = join(root, '..', 'lightningpanda');
+  if (statSync(sibling, { throwIfNoEntry: false })?.isFile()) return sibling;
+  if (platform !== 'darwin' || !['arm64', 'x64'].includes(arch)) {
+    throw new Error(`Lightningpanda has no bundled browser for ${platform}-${arch}. The browser supports macOS 14+ on arm64 and x64. Use Lightningpanda.connect() for a remote browser, or set LIGHTNINGPANDA_BIN.`);
+  }
+  throw new Error(`Missing bundled browser: ${bundled}. Reinstall @povio/lightning-panda or set LIGHTNINGPANDA_BIN to a built browser.`);
+}

package/src/cdp.ts

@@ -0,0 +1,72 @@
+// Minimal CDP client over the runtime's WebSocket (Bun, Node >= 22): flat
+// sessions, one promise per command, no event subscriptions.
+
+export class CdpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly code: number,
+    message: string,
+    /** The error's `data` (a failed `matchScreenshot` carries its images). */
+    readonly data?: unknown,
+  ) {
+    super(`${method}: ${message}`);
+  }
+}
+
+type Pending = { method: string; resolve: (v: any) => void; reject: (e: Error) => void };
+
+export class Cdp {
+  private nextId = 1;
+  private pending = new Map<number, Pending>();
+  private closed: Error | null = null;
+
+  private constructor(private ws: WebSocket) {
+    ws.addEventListener('message', (ev) => this.onMessage(String(ev.data)));
+    ws.addEventListener('close', () => this.fail(new Error('CDP connection closed')));
+    ws.addEventListener('error', () => this.fail(new Error('CDP connection failed')));
+  }
+
+  static open(url: string): Promise<Cdp> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+      ws.addEventListener('open', () => resolve(new Cdp(ws)), { once: true });
+      ws.addEventListener('error', () => reject(new Error(`cannot connect to ${url}`)), { once: true });
+    });
+  }
+
+  send<T = any>(method: string, params: object = {}, sessionId?: string): Promise<T> {
+    if (this.closed) return Promise.reject(this.closed);
+    const id = this.nextId++;
+    const msg: Record<string, unknown> = { id, method, params };
+    if (sessionId) msg.sessionId = sessionId;
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { method, resolve, reject });
+      this.ws.send(JSON.stringify(msg));
+    });
+  }
+
+  /** Sends without waiting; a failure is ignored (cleanup). */
+  post(method: string, params: object = {}, sessionId?: string): void {
+    this.send(method, params, sessionId).catch(() => {});
+  }
+
+  close(): void {
+    this.ws.close();
+  }
+
+  private onMessage(text: string) {
+    const msg = JSON.parse(text);
+    if (typeof msg.id !== 'number') return; // events are not used
+    const p = this.pending.get(msg.id);
+    if (!p) return;
+    this.pending.delete(msg.id);
+    if (msg.error) p.reject(new CdpError(p.method, msg.error.code, msg.error.message, msg.error.data));
+    else p.resolve(msg.result);
+  }
+
+  private fail(error: Error) {
+    this.closed ??= error;
+    for (const p of this.pending.values()) p.reject(error);
+    this.pending.clear();
+  }
+}

package/src/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { resolveBinary } from './binary.js';
+
+try {
+  const child = spawn(resolveBinary(), process.argv.slice(2), { stdio: 'inherit' });
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const;
+  const forward = (signal: NodeJS.Signals) => { child.kill(signal); };
+  for (const signal of signals) process.on(signal, forward);
+  const cleanup = () => { for (const signal of signals) process.off(signal, forward); };
+  child.once('error', (error) => {
+    cleanup();
+    console.error(`lightningpanda: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.once('exit', (code, signal) => {
+    cleanup();
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+} catch (error) {
+  console.error(`lightningpanda: ${error instanceof Error ? error.message : error}`);
+  process.exitCode = 1;
+}