sliccy 6.39.1 → 6.41.0

package/README.md

@@ -11,7 +11,7 @@ If this scares, confuses, or excites you, keep reading.
 
 # slicc — Self-Licking Ice Cream Cone
 
-[![40% Vibe_Coded](https://img.shields.io/badge/40%25-Vibe_Coded-ff69b4?style=for-the-badge&logo=claude&logoColor=white)](https://github.com/ai-ecoverse/vibe-coded-badge-action)
+[![41% Vibe_Coded](https://img.shields.io/badge/41%25-Vibe_Coded-ff69b4?style=for-the-badge&logo=claude&logoColor=white)](https://github.com/ai-ecoverse/vibe-coded-badge-action)
 
 [![npm](https://img.shields.io/npm/v/sliccy)](https://www.npmjs.com/package/sliccy)
 

package/dist/node-server/electron-controller.d.ts

@@ -94,7 +94,34 @@ export declare function resolveFetchProxyOrigin(targetUrl: string, servePort: nu
 export interface ThinBootstrapSet {
     leader: string;
     follower: string;
+    /**
+     * Status-only overlay bootstrap: injects the launcher with NO app-url (no
+     * iframe) and a message explaining the app blocks the embedded panel. Used
+     * for egress-blocked apps (e.g. Signal) so the user sees the launcher + a
+     * clear note instead of a silent blank panel.
+     */
+    status: string;
 }
+/**
+ * Empty-viewport message shown by the status-only overlay for an app that
+ * denies the overlay iframe's network egress. Kept in sync with swift-server's
+ * `overlayStatusMessageEgressBlocked`.
+ */
+export declare const OVERLAY_STATUS_MESSAGE_EGRESS_BLOCKED = "SLICC is attached to this app, but it blocks embedded panels. Drive it from the SLICC leader window.";
+/**
+ * CDP `Network.loadingFailed` `errorText` values that mean the *app itself*
+ * denied the overlay's document request at the network layer — not a CSP block.
+ * Signal (and other locked-down Electron apps) proxy all renderer network
+ * through their main process and deny external requests with
+ * `net::ERR_ACCESS_DENIED`, BENEATH the layer where `Page.setBypassCSP` or the
+ * CDP Fetch proxy operate — so the reload/Fetch escalation cannot help and must
+ * be skipped. Unlike a CSP block, the thrown probe (`OVERLAY_LOADED_PROBE_EXPRESSION`)
+ * can't distinguish this from a successful cross-origin load (both throw), so we
+ * detect it authoritatively from the failed document request instead.
+ */
+export declare const OVERLAY_EGRESS_BLOCK_ERROR_TEXTS: readonly string[];
+/** True when `errorText` is one of {@link OVERLAY_EGRESS_BLOCK_ERROR_TEXTS}. */
+export declare function isOverlayEgressBlockError(errorText: string | undefined): boolean;
 /**
  * JS probe that reports whether the overlay iframe actually loaded. Walks the
  * `<slicc-launcher>` host's (open) shadow root to find the iframe
@@ -107,6 +134,13 @@ export interface ThinBootstrapSet {
  * so the overlay did not load and the setBypassCSP escalation must fire.
  * Returns `'ok'` only from the catch; otherwise `'no-host' / 'no-iframe' /
  * 'no-src' / 'blank:<href>'`.
+ *
+ * CAVEAT: a *network-layer* block (the app denying the overlay's document
+ * request with `net::ERR_ACCESS_DENIED`) swaps to a CROSS-origin `chrome-error`
+ * page whose href access ALSO throws — indistinguishable here from a real load.
+ * That case is detected authoritatively from `Network.loadingFailed`
+ * (see {@link isOverlayEgressBlockError}); this probe's `'ok'` is overridden by
+ * the connection's `egressBlocked` flag so it is never recorded as loaded.
  */
 export declare const OVERLAY_LOADED_PROBE_EXPRESSION = "(function() {\n          var host = document.getElementById('slicc-electron-overlay-root');\n          if (!host || !host.shadowRoot) return 'no-host';\n          var iframe = host.shadowRoot.querySelector('iframe');\n          if (!iframe) return 'no-iframe';\n          if (!iframe.src) return 'no-src';\n          try {\n            // Thin-bridge overlay is ALWAYS cross-origin (hosted webapp) vs the app\n            // document. A committed cross-origin navigation makes this access THROW.\n            // Any READABLE href means the cross-origin nav did NOT commit \u2014 still\n            // about:blank, or swapped to chrome-error://chromewebdata/ by a CSP block \u2014\n            // so the overlay did NOT load and the setBypassCSP escalation must fire.\n            var href = iframe.contentWindow && iframe.contentWindow.location ? iframe.contentWindow.location.href : '';\n            return 'blank:' + href;\n          } catch (e) {\n            return 'ok';\n          }\n        })()";
 /**
@@ -130,12 +164,32 @@ export declare class ElectronOverlayInjector {
     private readonly presenceCheckIntervalMs;
     private readonly connections;
     private readonly cspBypassedTargets;
+    /**
+     * Per-process bridge token, present in every overlay app URL. Used to
+     * correlate a `Network.loadingFailed` back to OUR overlay iframe's document
+     * request (vs the app's own frames) when detecting an egress block.
+     */
+    private readonly bridgeToken;
+    /**
+     * Targets whose overlay iframe was denied at the network layer by the app
+     * itself (e.g. Signal → `net::ERR_ACCESS_DENIED`). The reload/Fetch-proxy
+     * escalation cannot rescue these, so once a target is here we stop escalating
+     * and never record it as CSP-bypassed (which would falsely read as loaded).
+     */
+    private readonly egressBlockedTargets;
     /**
      * URL of the target currently elected as the pinned leader. Cleared by
      * `syncTargets` when that target disappears so the next injection
      * re-elects a fresh leader.
      */
     private leaderTargetUrl;
+    /**
+     * Fired ONCE when the app is first detected to block renderer egress, so the
+     * runtime can start the headless CDP-over-CDP follower (`ElectronTrayFollower`)
+     * for this app. The hosted overlay can never load in such apps, so exposing
+     * their CDP to the tray leader is the only way to drive them.
+     */
+    private readonly onEgressBlocked?;
     private syncTimer;
     private syncing;
     private constructor();
@@ -150,6 +204,8 @@ export declare class ElectronOverlayInjector {
          * bundled overlay path was retired.
          */
         thinBridge: ThinBridgeConfig;
+        /** Start the headless CDP-over-CDP follower when egress-block is detected. */
+        onEgressBlocked?: (targetUrl: string) => void;
     }): Promise<ElectronOverlayInjector>;
     /**
      * Test-only factory: skips bundle loading and lets tests drive the per-target
@@ -160,6 +216,8 @@ export declare class ElectronOverlayInjector {
         cdpPort?: number;
         servePort: number;
         thinBootstraps?: ThinBootstrapSet;
+        bridgeToken?: string;
+        onEgressBlocked?: (targetUrl: string) => void;
         probeDelayMs?: number;
         presenceCheckIntervalMs?: number;
     }): ElectronOverlayInjector;
@@ -173,6 +231,10 @@ export declare class ElectronOverlayInjector {
     _testingSeedBypassedTarget(url: string): void;
     /** Test-only: snapshot the per-target "already bypassed" guard set. */
     _testingBypassedTargets(): ReadonlySet<string>;
+    /** Test-only: snapshot the set of targets marked egress-blocked. */
+    _testingEgressBlockedTargets(): ReadonlySet<string>;
+    /** Test-only: seed a target as already egress-blocked. */
+    _testingSeedEgressBlockedTarget(url: string): void;
     /** Test-only: drive a single `syncTargets` pass without `start()`'s interval. */
     _testingSyncTargets(): Promise<void>;
     /** Test-only: close any sockets opened by `_testingConnectToTarget`. */
@@ -262,5 +324,25 @@ export declare class ElectronOverlayInjector {
      * is no CDP reply for fulfill, and the response body is the document body.
      */
     private handleFetchRequestPaused;
+    /**
+     * Inspect a `Network.*` CDP event for the egress-block signal: track OUR
+     * overlay iframe's top-level Document request (matched by the per-process
+     * bridge token in its URL, so the app's own frames are ignored) and, when the
+     * app denies it at the network layer ({@link isOverlayEgressBlockError}), set
+     * `state.egressBlocked` and record the target. `Page.setBypassCSP` / the Fetch
+     * proxy operate above the layer that denies these, so escalation cannot help —
+     * the probe/escalation paths read `state.egressBlocked` to bail out instead of
+     * reload-churning and instead of falsely recording the target as loaded.
+     */
+    private handleNetworkEventForEgressBlock;
+    /**
+     * Show the status-only overlay (launcher + message, no iframe) on a target
+     * that blocks the embedded panel. Injects the status bootstrap now AND as a
+     * `Page.addScriptToEvaluateOnNewDocument` hook so it survives app reloads —
+     * the status hook is added after the role hook, so re-running both leaves the
+     * idempotent launcher in the status-only state (the launcher is collapsed, so
+     * there is no visible iframe flash).
+     */
+    private injectStatusOverlay;
     private connectToTarget;
 }

package/dist/node-server/electron-controller.js

@@ -478,6 +478,33 @@ function buildFulfillResponseHeaders(rawHeaders, contentLength) {
     }
     return { responseHeaders, strippedCSP };
 }
+/**
+ * Empty-viewport message shown by the status-only overlay for an app that
+ * denies the overlay iframe's network egress. Kept in sync with swift-server's
+ * `overlayStatusMessageEgressBlocked`.
+ */
+export const OVERLAY_STATUS_MESSAGE_EGRESS_BLOCKED = 'SLICC is attached to this app, but it blocks embedded panels. Drive it from the SLICC leader window.';
+/**
+ * CDP `Network.loadingFailed` `errorText` values that mean the *app itself*
+ * denied the overlay's document request at the network layer — not a CSP block.
+ * Signal (and other locked-down Electron apps) proxy all renderer network
+ * through their main process and deny external requests with
+ * `net::ERR_ACCESS_DENIED`, BENEATH the layer where `Page.setBypassCSP` or the
+ * CDP Fetch proxy operate — so the reload/Fetch escalation cannot help and must
+ * be skipped. Unlike a CSP block, the thrown probe (`OVERLAY_LOADED_PROBE_EXPRESSION`)
+ * can't distinguish this from a successful cross-origin load (both throw), so we
+ * detect it authoritatively from the failed document request instead.
+ */
+export const OVERLAY_EGRESS_BLOCK_ERROR_TEXTS = [
+    'net::ERR_ACCESS_DENIED',
+    'net::ERR_NETWORK_ACCESS_DENIED',
+    'net::ERR_BLOCKED_BY_CLIENT',
+    'net::ERR_BLOCKED_BY_ADMINISTRATOR',
+];
+/** True when `errorText` is one of {@link OVERLAY_EGRESS_BLOCK_ERROR_TEXTS}. */
+export function isOverlayEgressBlockError(errorText) {
+    return typeof errorText === 'string' && OVERLAY_EGRESS_BLOCK_ERROR_TEXTS.includes(errorText);
+}
 /**
  * JS probe that reports whether the overlay iframe actually loaded. Walks the
  * `<slicc-launcher>` host's (open) shadow root to find the iframe
@@ -490,6 +517,13 @@ function buildFulfillResponseHeaders(rawHeaders, contentLength) {
  * so the overlay did not load and the setBypassCSP escalation must fire.
  * Returns `'ok'` only from the catch; otherwise `'no-host' / 'no-iframe' /
  * 'no-src' / 'blank:<href>'`.
+ *
+ * CAVEAT: a *network-layer* block (the app denying the overlay's document
+ * request with `net::ERR_ACCESS_DENIED`) swaps to a CROSS-origin `chrome-error`
+ * page whose href access ALSO throws — indistinguishable here from a real load.
+ * That case is detected authoritatively from `Network.loadingFailed`
+ * (see {@link isOverlayEgressBlockError}); this probe's `'ok'` is overridden by
+ * the connection's `egressBlocked` flag so it is never recorded as loaded.
  */
 export const OVERLAY_LOADED_PROBE_EXPRESSION = `(function() {
           var host = document.getElementById('slicc-electron-overlay-root');
@@ -538,18 +572,40 @@ export class ElectronOverlayInjector {
     presenceCheckIntervalMs;
     connections = new Map();
     cspBypassedTargets = new Set();
+    /**
+     * Per-process bridge token, present in every overlay app URL. Used to
+     * correlate a `Network.loadingFailed` back to OUR overlay iframe's document
+     * request (vs the app's own frames) when detecting an egress block.
+     */
+    bridgeToken;
+    /**
+     * Targets whose overlay iframe was denied at the network layer by the app
+     * itself (e.g. Signal → `net::ERR_ACCESS_DENIED`). The reload/Fetch-proxy
+     * escalation cannot rescue these, so once a target is here we stop escalating
+     * and never record it as CSP-bypassed (which would falsely read as loaded).
+     */
+    egressBlockedTargets = new Set();
     /**
      * URL of the target currently elected as the pinned leader. Cleared by
      * `syncTargets` when that target disappears so the next injection
      * re-elects a fresh leader.
      */
     leaderTargetUrl = null;
+    /**
+     * Fired ONCE when the app is first detected to block renderer egress, so the
+     * runtime can start the headless CDP-over-CDP follower (`ElectronTrayFollower`)
+     * for this app. The hosted overlay can never load in such apps, so exposing
+     * their CDP to the tray leader is the only way to drive them.
+     */
+    onEgressBlocked;
     syncTimer = null;
     syncing = false;
-    constructor(cdpPort, servePort, thinBootstraps, probeDelayMs = 1500, presenceCheckIntervalMs = ELECTRON_OVERLAY_PRESENCE_CHECK_INTERVAL_MS) {
+    constructor(cdpPort, servePort, thinBootstraps, bridgeToken, onEgressBlocked, probeDelayMs = 1500, presenceCheckIntervalMs = ELECTRON_OVERLAY_PRESENCE_CHECK_INTERVAL_MS) {
         this.cdpPort = cdpPort;
         this.servePort = servePort;
         this.thinBootstraps = thinBootstraps;
+        this.bridgeToken = bridgeToken;
+        this.onEgressBlocked = onEgressBlocked;
         this.probeDelayMs = probeDelayMs;
         this.presenceCheckIntervalMs = presenceCheckIntervalMs;
     }
@@ -566,8 +622,13 @@ export class ElectronOverlayInjector {
                 bundleSource,
                 appUrl: buildThinOverlayAppUrl({ ...options.thinBridge, role: BRIDGE_ROLE_FOLLOWER }),
             }),
+            status: buildElectronOverlayBootstrapScript({
+                bundleSource,
+                appUrl: '',
+                statusMessage: OVERLAY_STATUS_MESSAGE_EGRESS_BLOCKED,
+            }),
         };
-        return new ElectronOverlayInjector(options.cdpPort, options.servePort, thinBootstraps);
+        return new ElectronOverlayInjector(options.cdpPort, options.servePort, thinBootstraps, options.thinBridge.bridgeToken, options.onEgressBlocked);
     }
     /**
      * Test-only factory: skips bundle loading and lets tests drive the per-target
@@ -575,7 +636,11 @@ export class ElectronOverlayInjector {
      * `_testing_*` hooks on `ElectronOverlayInjector`.
      */
     static _createForTesting(options) {
-        return new ElectronOverlayInjector(options.cdpPort ?? 9223, options.servePort, options.thinBootstraps ?? { leader: '/* test-leader */', follower: '/* test-follower */' }, options.probeDelayMs ?? 1500, options.presenceCheckIntervalMs ?? ELECTRON_OVERLAY_PRESENCE_CHECK_INTERVAL_MS);
+        return new ElectronOverlayInjector(options.cdpPort ?? 9223, options.servePort, options.thinBootstraps ?? {
+            leader: '/* test-leader */',
+            follower: '/* test-follower */',
+            status: '/* test-status */',
+        }, options.bridgeToken ?? 'test-bridge-token', options.onEgressBlocked, options.probeDelayMs ?? 1500, options.presenceCheckIntervalMs ?? ELECTRON_OVERLAY_PRESENCE_CHECK_INTERVAL_MS);
     }
     /** Test-only: snapshot the elected leader target URL (null when no leader). */
     _testingLeaderTargetUrl() {
@@ -597,6 +662,14 @@ export class ElectronOverlayInjector {
     _testingBypassedTargets() {
         return new Set(this.cspBypassedTargets);
     }
+    /** Test-only: snapshot the set of targets marked egress-blocked. */
+    _testingEgressBlockedTargets() {
+        return new Set(this.egressBlockedTargets);
+    }
+    /** Test-only: seed a target as already egress-blocked. */
+    _testingSeedEgressBlockedTarget(url) {
+        this.egressBlockedTargets.add(url);
+    }
     /** Test-only: drive a single `syncTargets` pass without `start()`'s interval. */
     async _testingSyncTargets() {
         await this.syncTargets();
@@ -842,6 +915,21 @@ export class ElectronOverlayInjector {
         console.log(`[electron-float] Connected to target, bypassed=${alreadyBypassed}, url=${target.url}`);
         send('Runtime.enable');
         send('Page.enable');
+        // A target already known to block renderer egress cannot load the hosted
+        // overlay by any escalation — show the status-only overlay (no iframe)
+        // instead of re-running the doomed iframe injection + probe. (The
+        // stripped-down CDP-over-CDP follower path drives these apps.)
+        if (this.egressBlockedTargets.has(target.url)) {
+            state.egressBlocked = true;
+            console.log(`[electron-float] ${target.url} blocks renderer egress — injecting status-only overlay`);
+            this.injectStatusOverlay(send);
+            return;
+        }
+        // Watch the overlay iframe's document request so an app that denies it at
+        // the network layer (e.g. Signal → net::ERR_ACCESS_DENIED) is detected and
+        // the doomed CSP/Fetch escalation is skipped (see
+        // `handleNetworkEventForEgressBlock`).
+        send('Network.enable');
         // Install the role bootstrap as a permanent new-document hook (parity with
         // swift-server) so a full document reload / load-driven navigation of this
         // already-connected target re-injects the overlay automatically. Without
@@ -887,12 +975,22 @@ export class ElectronOverlayInjector {
             setTimeout(async () => {
                 if (ws.readyState !== WebSocket.OPEN)
                     return;
+                // Egress-blocked apps deny the overlay's document request beneath the
+                // layer setBypassCSP / the Fetch proxy operate at, so escalation cannot
+                // help. The probe's throw-based `'ok'` can't tell this apart from a real
+                // cross-origin load, so `egressBlocked` is authoritative: bail out
+                // WITHOUT recording the target as bypassed/loaded.
+                if (state.egressBlocked)
+                    return;
                 const loaded = await this.probeOverlayIframeLoaded(ws, send);
-                if (loaded) {
+                if (loaded && !state.egressBlocked) {
                     console.log(`[electron-float] Overlay iframe loaded successfully — no CSP reload needed`);
                     this.cspBypassedTargets.add(target.url);
+                    send('Network.disable');
                     return;
                 }
+                if (state.egressBlocked)
+                    return;
                 // Phase 2: Page.setBypassCSP was already set — a simple reload should
                 // make the browser ignore CSP headers on the fresh navigation.
                 // Deliberately do NOT recordBypassed yet — if the CDP session
@@ -937,12 +1035,20 @@ export class ElectronOverlayInjector {
             setTimeout(async () => {
                 if (ws.readyState !== WebSocket.OPEN)
                     return;
+                // Network-egress block detected during/after the reload — the Fetch
+                // proxy can't help either (it intercepts above the denying layer), so
+                // stop here without recording the target as loaded.
+                if (state.egressBlocked)
+                    return;
                 const loaded = await this.probeOverlayIframeLoaded(ws, send);
-                if (loaded) {
+                if (loaded && !state.egressBlocked) {
                     console.log(`[electron-float] Overlay iframe loaded after CSP reload — no proxy needed`);
                     this.cspBypassedTargets.add(target.url);
+                    send('Network.disable');
                     return;
                 }
+                if (state.egressBlocked)
+                    return;
                 const fetchOrigin = resolveFetchProxyOrigin(target.url, this.servePort);
                 console.log(`[electron-float] CSP reload insufficient, escalating to Fetch proxy: target=${target.url} origin=${fetchOrigin}`);
                 state.fetchProxyActive = true;
@@ -1021,6 +1127,60 @@ export class ElectronOverlayInjector {
         }
         proxyReq.end();
     }
+    /**
+     * Inspect a `Network.*` CDP event for the egress-block signal: track OUR
+     * overlay iframe's top-level Document request (matched by the per-process
+     * bridge token in its URL, so the app's own frames are ignored) and, when the
+     * app denies it at the network layer ({@link isOverlayEgressBlockError}), set
+     * `state.egressBlocked` and record the target. `Page.setBypassCSP` / the Fetch
+     * proxy operate above the layer that denies these, so escalation cannot help —
+     * the probe/escalation paths read `state.egressBlocked` to bail out instead of
+     * reload-churning and instead of falsely recording the target as loaded.
+     */
+    handleNetworkEventForEgressBlock(msg, send, target, state) {
+        const params = msg.params;
+        if (!params)
+            return;
+        if (msg.method === 'Network.requestWillBeSent') {
+            if (params.type === 'Document' &&
+                typeof params.requestId === 'string' &&
+                typeof params.request?.url === 'string' &&
+                params.request.url.includes(this.bridgeToken)) {
+                state.overlayRequestIds.add(params.requestId);
+            }
+            return;
+        }
+        if (msg.method === 'Network.loadingFailed' &&
+            typeof params.requestId === 'string' &&
+            state.overlayRequestIds.has(params.requestId) &&
+            isOverlayEgressBlockError(params.errorText)) {
+            state.egressBlocked = true;
+            // Determination made — stop the Network event stream for this connection.
+            send('Network.disable');
+            if (!this.egressBlockedTargets.has(target.url)) {
+                this.egressBlockedTargets.add(target.url);
+                console.log(`[electron-float] Overlay blocked by app network egress (${params.errorText}); ` +
+                    `the hosted overlay cannot load in ${target.url} — skipping CSP/Fetch escalation. ` +
+                    `Egress-blocked apps need the CDP-over-CDP follower path.`);
+                // Start the headless CDP-over-CDP follower for this app (once).
+                this.onEgressBlocked?.(target.url);
+            }
+            // Replace the (blank-iframe) overlay with the status-only launcher.
+            this.injectStatusOverlay(send);
+        }
+    }
+    /**
+     * Show the status-only overlay (launcher + message, no iframe) on a target
+     * that blocks the embedded panel. Injects the status bootstrap now AND as a
+     * `Page.addScriptToEvaluateOnNewDocument` hook so it survives app reloads —
+     * the status hook is added after the role hook, so re-running both leaves the
+     * idempotent launcher in the status-only state (the launcher is collapsed, so
+     * there is no visible iframe flash).
+     */
+    injectStatusOverlay(send) {
+        send('Page.addScriptToEvaluateOnNewDocument', { source: this.thinBootstraps.status });
+        send('Runtime.evaluate', { expression: this.thinBootstraps.status, awaitPromise: false });
+    }
     connectToTarget(target) {
         const targetId = target.webSocketDebuggerUrl;
         const ws = new WebSocket(targetId);
@@ -1035,6 +1195,8 @@ export class ElectronOverlayInjector {
             pendingReload: false,
             pendingCspEscalation: false,
             fetchProxyActive: false,
+            egressBlocked: false,
+            overlayRequestIds: new Set(),
         };
         // Periodic presence re-check: covers SPAs that re-render their DOM root
         // (evicting the overlay) without firing a navigation event. Cleared on
@@ -1079,6 +1241,11 @@ export class ElectronOverlayInjector {
                 if (msg.method === 'Fetch.requestPaused' && state.fetchProxyActive) {
                     this.handleFetchRequestPaused(ws, send, msg);
                 }
+                // Egress-block detection: track OUR overlay iframe's Document request
+                // (matched by the per-process bridge token in the URL) and, if the app
+                // denies it at the network layer, mark the target so the doomed
+                // reload/Fetch escalation is skipped and it is never recorded as loaded.
+                this.handleNetworkEventForEgressBlock(msg, send, target, state);
             }
             catch {
                 // Ignore parse errors for non-JSON messages

package/dist/node-server/electron-federated-cdp.d.ts

@@ -0,0 +1,73 @@
+import { type FollowerToLeaderMessage } from './_shared/index.js';
+/** A CDP target as returned by `/json/list`. */
+export interface FederatedCdpInspectableTarget {
+    id: string;
+    type: string;
+    title?: string;
+    url: string;
+    webSocketDebuggerUrl?: string;
+}
+/** Leader → follower CDP request (the `cdp.request` tray-sync variant). */
+export interface FederatedCdpRequest {
+    requestId: string;
+    localTargetId: string;
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}
+/**
+ * Build a `targets.advertise` message advertising the app's page targets to the
+ * leader (which namespaces them into its aggregated `targets.registry`). Only
+ * `page`-type targets are exposed — devtools/service-worker/etc. are not
+ * driveable follower surfaces. `targetId` is the app's LOCAL CDP target id.
+ */
+export declare function buildTargetsAdvertise(runtimeId: string, targets: FederatedCdpInspectableTarget[]): Extract<FollowerToLeaderMessage, {
+    type: 'targets.advertise';
+}>;
+/**
+ * Translate a raw CDP result/error into the `cdp.response` message(s) to send
+ * back to the leader. Delegates to the shared `sendCDPResponse` chunker so an
+ * oversize result is split into `chunkData` frames the leader reassembles.
+ */
+export declare function buildCdpResponses(requestId: string, outcome: {
+    result?: Record<string, unknown>;
+    error?: string;
+}): Array<Extract<FollowerToLeaderMessage, {
+    type: 'cdp.response';
+}>>;
+/** Translate a raw CDP event frame into a `cdp.event` tray-sync message. */
+export declare function buildCdpEvent(frame: {
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}): Extract<FollowerToLeaderMessage, {
+    type: 'cdp.event';
+}>;
+/**
+ * Connects to the attached app's raw CDP and relays tray-sync CDP messages
+ * to/from a leader over an injected transport. Transparent: the leader manages
+ * Target attachment / sessions itself (via forwarded `Target.*` requests), so
+ * this servicer only maps `requestId ↔ CDP id` and translates envelopes.
+ */
+export declare class ElectronFederatedCdp {
+    private readonly runtimeId;
+    private readonly send;
+    private ws;
+    private nextCdpId;
+    /** CDP frame id → leader requestId, for correlating responses. */
+    private readonly pending;
+    constructor(options: {
+        runtimeId: string;
+        send: (message: FollowerToLeaderMessage) => void;
+    });
+    /** Open the CDP connection to the browser-level debugger endpoint. */
+    connect(browserWebSocketDebuggerUrl: string): Promise<void>;
+    /** Advertise the app's page targets to the leader (from `/json/list`). */
+    advertiseTargets(targets: FederatedCdpInspectableTarget[]): void;
+    /** Service one leader `cdp.request`: forward it to the app's CDP (preserving
+     *  `sessionId`) and correlate the eventual response by requestId. */
+    handleCdpRequest(request: FederatedCdpRequest): void;
+    /** Close the CDP connection and reject any in-flight requests. */
+    stop(): void;
+    private onCdpFrame;
+}

package/dist/node-server/electron-federated-cdp.js

@@ -0,0 +1,166 @@
+// Server-side federated-CDP servicer — the "expose CDP over CDP" core for
+// egress-blocked Electron apps (e.g. Signal).
+//
+// A normal SLICC follower runs the webapp in the target's renderer and lets the
+// leader drive its browser over the tray sync protocol (`cdp.request` →
+// `cdp.response`/`cdp.event`, `targets.registry`). Signal's renderer blocks all
+// network egress, so the webapp can't run there — but the slicc-server DOES have
+// the app's raw CDP (the `--cdp-port` it launched Signal with). This servicer
+// makes the SERVER the follower's CDP surface: it connects to that raw CDP and
+// translates the leader's tray-sync CDP messages to/from it, transparently.
+//
+// It is TRANSPORT-AGNOSTIC: the caller supplies a `send(FollowerToLeaderMessage)`
+// sink and feeds it leader `cdp.request`s via `handleCdpRequest`. Wiring the
+// WebRTC data channel (tray-webrtc) that carries these messages to/from the
+// leader is a separate phase — WebRTC is proven to work from Signal's renderer,
+// and its signalling tunnels over the CDP binding. The translation core here is
+// pure + unit-tested, and the CDP driver is validated against a live target.
+import { sendCDPResponse, } from './_shared/index.js';
+import { WebSocket } from 'ws';
+/**
+ * Build a `targets.advertise` message advertising the app's page targets to the
+ * leader (which namespaces them into its aggregated `targets.registry`). Only
+ * `page`-type targets are exposed — devtools/service-worker/etc. are not
+ * driveable follower surfaces. `targetId` is the app's LOCAL CDP target id.
+ */
+export function buildTargetsAdvertise(runtimeId, targets) {
+    const entries = targets
+        .filter((t) => t.type === 'page')
+        .map((t) => ({
+        targetId: t.id,
+        title: t.title ?? '',
+        url: t.url,
+        kind: 'browser',
+    }));
+    return { type: 'targets.advertise', targets: entries, runtimeId };
+}
+/**
+ * Translate a raw CDP result/error into the `cdp.response` message(s) to send
+ * back to the leader. Delegates to the shared `sendCDPResponse` chunker so an
+ * oversize result is split into `chunkData` frames the leader reassembles.
+ */
+export function buildCdpResponses(requestId, outcome) {
+    const messages = [];
+    sendCDPResponse({
+        send: (message) => {
+            if (message.type === 'cdp.response') {
+                messages.push(message);
+            }
+            return true;
+        },
+    }, requestId, outcome.result, outcome.error);
+    return messages;
+}
+/** Translate a raw CDP event frame into a `cdp.event` tray-sync message. */
+export function buildCdpEvent(frame) {
+    return {
+        type: 'cdp.event',
+        method: frame.method,
+        params: frame.params ?? {},
+        sessionId: frame.sessionId,
+    };
+}
+/**
+ * Connects to the attached app's raw CDP and relays tray-sync CDP messages
+ * to/from a leader over an injected transport. Transparent: the leader manages
+ * Target attachment / sessions itself (via forwarded `Target.*` requests), so
+ * this servicer only maps `requestId ↔ CDP id` and translates envelopes.
+ */
+export class ElectronFederatedCdp {
+    runtimeId;
+    send;
+    ws = null;
+    nextCdpId = 1;
+    /** CDP frame id → leader requestId, for correlating responses. */
+    pending = new Map();
+    constructor(options) {
+        this.runtimeId = options.runtimeId;
+        this.send = options.send;
+    }
+    /** Open the CDP connection to the browser-level debugger endpoint. */
+    async connect(browserWebSocketDebuggerUrl) {
+        const ws = new WebSocket(browserWebSocketDebuggerUrl);
+        this.ws = ws;
+        ws.on('message', (data) => this.onCdpFrame(data.toString()));
+        await new Promise((resolve, reject) => {
+            ws.once('open', () => resolve());
+            ws.once('error', (err) => reject(err));
+        });
+    }
+    /** Advertise the app's page targets to the leader (from `/json/list`). */
+    advertiseTargets(targets) {
+        this.send(buildTargetsAdvertise(this.runtimeId, targets));
+    }
+    /** Service one leader `cdp.request`: forward it to the app's CDP (preserving
+     *  `sessionId`) and correlate the eventual response by requestId. */
+    handleCdpRequest(request) {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            for (const message of buildCdpResponses(request.requestId, { error: 'cdp-not-connected' })) {
+                this.send(message);
+            }
+            return;
+        }
+        const id = this.nextCdpId++;
+        this.pending.set(id, request.requestId);
+        const frame = { id, method: request.method, params: request.params ?? {} };
+        if (request.sessionId)
+            frame.sessionId = request.sessionId;
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch (err) {
+            // A socket that goes CLOSING between the OPEN check above and here makes
+            // `ws.send` throw synchronously; without this the leader's requestId is
+            // stranded until `stop()` rejects it (long after the leader's own
+            // timeout). Mirrors FederatedCDPServicer.handleCdpRequest in swift-server.
+            this.pending.delete(id);
+            for (const message of buildCdpResponses(request.requestId, {
+                error: `cdp-send-failed: ${err instanceof Error ? err.message : String(err)}`,
+            })) {
+                this.send(message);
+            }
+        }
+    }
+    /** Close the CDP connection and reject any in-flight requests. */
+    stop() {
+        for (const requestId of this.pending.values()) {
+            for (const message of buildCdpResponses(requestId, { error: 'cdp-closed' })) {
+                this.send(message);
+            }
+        }
+        this.pending.clear();
+        try {
+            this.ws?.close();
+        }
+        catch {
+            // ignore close failures
+        }
+        this.ws = null;
+    }
+    onCdpFrame(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        // A response carries an `id`; an event carries a `method` and no `id`.
+        if (typeof frame.id === 'number') {
+            const requestId = this.pending.get(frame.id);
+            if (requestId === undefined)
+                return;
+            this.pending.delete(frame.id);
+            const outcome = frame.error
+                ? { error: frame.error.message ?? 'cdp-error' }
+                : { result: frame.result ?? {} };
+            for (const message of buildCdpResponses(requestId, outcome))
+                this.send(message);
+            return;
+        }
+        if (typeof frame.method === 'string') {
+            this.send(buildCdpEvent({ method: frame.method, params: frame.params, sessionId: frame.sessionId }));
+        }
+    }
+}