@winstonfassett/webdev-gateway 0.1.0-alpha.0

package/dist/cdp-relay.d.ts

@@ -0,0 +1,110 @@
+/**
+ * CDP Relay — bridges between Playwright and the Chrome extension.
+ *
+ * Based on Playwriter's proven relay pattern (github.com/remorses/playwriter).
+ * Supports multiple concurrent Playwright/CDP clients, each with session-scoped
+ * event routing.
+ *
+ * Passive/on-demand debugging:
+ *   Extension detects dev pages and announces them as "available" without attaching
+ *   the debugger. The relay requests debugging only when an agent needs CDP access
+ *   (via ensureDebugging()). After a period of inactivity (idle TTL), the relay
+ *   sends 'releaseDebug' to detach the debugger and stop the browser banner.
+ *
+ * WebSocket endpoints:
+ *   /__cdp-extension     — extension connects here
+ *   /devtools/browser/*  — Playwright clients connect here via connectOverCDP
+ *
+ * HTTP endpoints (Playwright discovery):
+ *   /json/version   — browser info with rewritten webSocketDebuggerUrl
+ *   /json/list      — list of attached targets
+ *
+ * Protocol (extension ↔ relay):
+ *   EXT→RELAY availability: { method: 'tabAvailable', params: { tabId, url, serverId, projectId } }
+ *   EXT→RELAY availability: { method: 'tabUnavailable', params: { tabId } }
+ *   RELAY→EXT control:      { method: 'requestDebug', params: { tabId? } }
+ *   RELAY→EXT control:      { method: 'releaseDebug', params: { tabId? } }
+ *   EXT→RELAY events:       { method: 'forwardCDPEvent', params: { sessionId, method, params } }
+ *   EXT→RELAY responses:    { id, result } or { id, error }
+ *   RELAY→EXT commands:     { id, method: 'forwardCDPCommand', params: { sessionId, method, params } }
+ *
+ * CDP commands handled locally (not forwarded):
+ *   Browser.getVersion, Browser.setDownloadBehavior, Target.setDiscoverTargets,
+ *   Target.attachToTarget, Target.getTargetInfo, Target.getTargets
+ *
+ * CDP commands with special handling:
+ *   Target.setAutoAttach — forward, then synthesize Target.attachedToTarget for known targets
+ *   Runtime.enable — forward, then wait for executionContextCreated before responding
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Page } from '@xmorse/playwright-core';
+export interface CDPRelayOptions {
+    gatewayPort: number;
+    /** Idle timeout in ms before auto-releasing debugging. Default: 5 minutes. 0 = no auto-release. */
+    idleTimeoutMs?: number;
+}
+export declare class CDPRelay {
+    private extensionWs;
+    private extensionWss;
+    private playwrightWss;
+    private clients;
+    private targets;
+    private availableTabs;
+    private pendingCommands;
+    private nextCommandId;
+    private gatewayPort;
+    private events;
+    private pwBrowser;
+    private pwConnecting;
+    private debuggingActive;
+    private debuggingRequested;
+    private idleTimeoutMs;
+    private idleTimer;
+    /** Cached refs from last a11y_snapshot call — maps ref string to element info */
+    refCache: Map<string, import('./playwright-commands.js').RefEntry> | null;
+    constructor(options: CDPRelayOptions);
+    /** Debugging is active and has targets */
+    get isAvailable(): boolean;
+    /** Extension is connected and has available tabs — debugging can be activated */
+    get canActivate(): boolean;
+    /**
+     * Ensure debugging is active. If not, request it from the extension and wait
+     * for targets to appear. Returns true if debugging is active after the call.
+     * Resets the idle timer on every call.
+     */
+    ensureDebugging(): Promise<boolean>;
+    /**
+     * Request the extension to start debugging all available tabs.
+     * Waits up to 5s for at least one target to appear.
+     */
+    requestDebugging(): Promise<boolean>;
+    /**
+     * Release debugging — detach debugger from all tabs.
+     * The extension will send Target.detachedFromTarget events.
+     */
+    releaseDebugging(): void;
+    private resetIdleTimer;
+    private clearIdleTimer;
+    /** Get all Playwright pages via the persistent CDP connection */
+    getPages(): Promise<Page[]>;
+    /** Get a Playwright page, optionally matched by dev server port */
+    getPage(serverPort?: number): Promise<Page | null>;
+    /** Get a CDP session for a page (using getExistingCDPSession, not newCDPSession) */
+    getCDPSession(page: Page): Promise<any>;
+    private ensurePlaywrightConnection;
+    private disconnectPlaywright;
+    handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+    /** Handle CDP control actions. Returns response object or null if not matched. */
+    handleAction(url: string): object | null;
+    handleHttp(url: string): object | null;
+    private onExtensionConnect;
+    private onExtensionMessage;
+    private onPlaywrightConnect;
+    private onPlaywrightMessage;
+    private routeCommand;
+    private sendToClient;
+    private sendToExtension;
+    close(): void;
+}
+//# sourceMappingURL=cdp-relay.d.ts.map

package/dist/cdp-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-relay.d.ts","sourceRoot":"","sources":["../src/cdp-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAW,IAAI,EAAkB,MAAM,yBAAyB,CAAA;AAE5E,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AA0BD,qBAAa,QAAQ;IACnB,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,eAAe,CAInB;IACJ,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAAQ;IAG5B,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,kBAAkB,CAAQ;IAClC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAA6C;IAE9D,iFAAiF;IACjF,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,0BAA0B,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAO;gBAEpE,OAAO,EAAE,eAAe;IASpC,0CAA0C;IAC1C,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,iFAAiF;IACjF,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IASzC;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAiC1C;;;OAGG;IACH,gBAAgB;IAehB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,cAAc;IAOtB,iEAAiE;IAC3D,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAMjC,mEAAmE;IAC7D,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IA8BxD,oFAAoF;IAC9E,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC;YAI/B,0BAA0B;IA0BxC,OAAO,CAAC,oBAAoB;IAS5B,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAyB9E,kFAAkF;IAClF,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkBxC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA2BtC,OAAO,CAAC,kBAAkB;IAiC1B,OAAO,CAAC,kBAAkB;IA0F1B,OAAO,CAAC,mBAAmB;YAyBb,mBAAmB;YAqCnB,YAAY;IA2H1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,eAAe;IAuBvB,KAAK;CAgBN"}