capdebug 0.1.0 → 0.3.0

package/dist/remote/buffer.d.ts

@@ -0,0 +1,13 @@
+import type { CapDebugEvent } from '../types';
+export declare class RemoteEventBuffer {
+    private buffer;
+    private maxCapacity;
+    private droppedCount;
+    constructor(maxCapacity?: number);
+    push(event: CapDebugEvent): void;
+    flush(): CapDebugEvent[];
+    clear(): void;
+    size(): number;
+    getDroppedCount(): number;
+    incrementDropped(): void;
+}

package/dist/remote/desktop-viewer-html.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTML template for the Desktop Remote Viewer (http://localhost:4783).
+ * Contains full client-side WebRTC host logic, real-time log stream UI,
+ * filtering, JSON inspection, and remote controls.
+ */
+export declare function getDesktopViewerHtml(options: {
+    sessionId: string;
+    secret: string;
+    signalingUrl: string;
+}): string;

package/dist/remote/pairing-page-html.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTML template for the mobile pairing redirect page (/pair).
+ * Served when the user scans the terminal QR code.
+ */
+export declare function getPairingPageHtml(options: {
+    sessionId: string;
+    signalingUrl: string;
+}): string;

package/dist/remote/pairing.d.ts

@@ -0,0 +1,34 @@
+import type { PairingSession } from './types';
+export interface ParsedPairingInfo {
+    sessionId: string;
+    secret: string;
+    signalingUrl?: string;
+    rawUrl: string;
+}
+export declare class PairingHelper {
+    /**
+     * Creates a new pairing session with given TTL (default 5 minutes).
+     */
+    static createSession(ttlMs?: number): PairingSession;
+    /**
+     * Generates a short, human-readable session ID (e.g. "K7P4-M2" or "7HQ2-9X").
+     */
+    static generateSessionId(): string;
+    /**
+     * Generates a cryptographically strong 128-bit random secret string.
+     */
+    static generateSecret(): string;
+    /**
+     * Formats a web pairing URL where the secret is stored strictly in the URL fragment (#SECRET).
+     */
+    static formatPairingUrl(baseUrl: string, sessionId: string, secret: string): string;
+    /**
+     * Formats a Capacitor mobile deep link URL.
+     */
+    static formatDeepLinkUrl(sessionId: string, secret: string, signalingUrl?: string): string;
+    /**
+     * Parses a web pairing URL or Capacitor deep-link URL into session and secret components.
+     */
+    static parseUrl(urlStr: string): ParsedPairingInfo | null;
+    private static getRandomBytes;
+}

package/dist/remote/protocol.d.ts

@@ -0,0 +1,14 @@
+import type { CapDebugEvent } from '../types';
+import type { ControlCommand, RemoteMessage } from './types';
+export declare const PROTOCOL_VERSION = 1;
+export declare class RemoteProtocol {
+    static createHello(capdebugVersion?: string, platform?: string, deviceName?: string): RemoteMessage;
+    static createHelloAck(): RemoteMessage;
+    static createEvent(event: CapDebugEvent): RemoteMessage;
+    static createBatch(events: CapDebugEvent[]): RemoteMessage;
+    static createControl(command: ControlCommand): RemoteMessage;
+    static createPing(timestamp?: number): RemoteMessage;
+    static createPong(pingTimestamp: number): RemoteMessage;
+    static serialize(message: RemoteMessage): string;
+    static parse(raw: string): RemoteMessage | null;
+}

package/dist/remote/remote-manager.d.ts

@@ -0,0 +1,19 @@
+import type { CapDebugStore } from '../store';
+import type { ConnectionDiagnostics, PairingConfig, TransportStatus } from './types';
+import { WebRTCTransport } from './webrtc-transport';
+export declare class RemoteManager {
+    private transport;
+    private store;
+    private isListening;
+    private eventListener;
+    constructor(store: CapDebugStore);
+    get activeTransport(): WebRTCTransport;
+    connect(config: PairingConfig): Promise<void>;
+    disconnect(): void;
+    status(): TransportStatus;
+    getDiagnostics(): ConnectionDiagnostics;
+    handlePairingUrl(url: string): Promise<boolean>;
+    private startEventListener;
+    private stopEventListener;
+    private setupControlHandler;
+}

package/dist/remote/signaling.d.ts

@@ -0,0 +1,27 @@
+import type { PairingSessionInfo, SignalingMessage } from './types';
+export interface SignalingTransport {
+    createSession(ttlSeconds?: number): Promise<PairingSessionInfo>;
+    joinSession(sessionId: string, secret: string): Promise<void>;
+    send(message: SignalingMessage): Promise<void>;
+    onMessage(callback: (message: SignalingMessage) => void): () => void;
+    close(): void;
+}
+export declare class HttpSseSignalingClient implements SignalingTransport {
+    private baseUrl;
+    private sessionId;
+    private secret;
+    private role;
+    private eventSource;
+    private listeners;
+    private isClosed;
+    private pollTimer;
+    constructor(baseUrl: string);
+    createSession(ttlSeconds?: number): Promise<PairingSessionInfo>;
+    joinSession(sessionId: string, secret: string): Promise<void>;
+    send(message: SignalingMessage): Promise<void>;
+    onMessage(callback: (message: SignalingMessage) => void): () => void;
+    close(): void;
+    private connectEventStream;
+    private startPolling;
+    private dispatchMessage;
+}

package/dist/remote/transport.d.ts

@@ -0,0 +1,15 @@
+import type { CapDebugEvent } from '../types';
+import type { ConnectionDiagnostics, ControlCommand, PairingConfig, TransportStatus } from './types';
+export interface CapDebugTransport {
+    readonly id: string;
+    connect(config: PairingConfig): Promise<void>;
+    send(event: CapDebugEvent): void;
+    sendControl(command: ControlCommand): void;
+    disconnect(): void;
+    getStatus(): TransportStatus;
+    getDiagnostics(): ConnectionDiagnostics;
+    onEvent(callback: (event: CapDebugEvent) => void): () => void;
+    onControl(callback: (command: ControlCommand) => void): () => void;
+    onStatusChange(callback: (status: TransportStatus) => void): () => void;
+    onDiagnostics(callback: (diag: ConnectionDiagnostics) => void): () => void;
+}

package/dist/remote/types.d.ts

@@ -0,0 +1,69 @@
+import type { CapDebugEvent } from '../types';
+export type SessionStatus = 'waiting' | 'peer-joined' | 'negotiating' | 'connected' | 'expired' | 'closed';
+export interface PairingSession {
+    id: string;
+    createdAt: number;
+    expiresAt: number;
+    status: SessionStatus;
+}
+export interface PairingSessionInfo {
+    sessionId: string;
+    secret: string;
+    createdAt: number;
+    expiresAt: number;
+    signalingUrl: string;
+    pairingUrl: string;
+    deepLinkUrl: string;
+}
+export interface PairingConfig {
+    sessionId: string;
+    secret: string;
+    signalingUrl?: string;
+    iceServers?: RTCIceServer[];
+    isHost?: boolean;
+}
+export type SignalingMessageType = 'join' | 'peer-joined' | 'offer' | 'answer' | 'ice-candidate' | 'disconnect' | 'error';
+export interface SignalingMessage {
+    sessionId: string;
+    secret: string;
+    type: SignalingMessageType;
+    sender: 'host' | 'peer';
+    payload?: any;
+    timestamp?: number;
+}
+export type TransportStatus = 'disconnected' | 'connecting' | 'signaling' | 'connected' | 'reconnecting' | 'failed';
+export interface ConnectionDiagnostics {
+    transport: 'webrtc' | 'local' | 'mock';
+    status: TransportStatus;
+    iceConnectionState?: string;
+    iceGatheringState?: string;
+    signalingState?: string;
+    connectionState?: string;
+    candidateType?: string;
+    protocol?: string;
+    route?: 'direct / LAN' | 'STUN / WAN' | 'relay / TURN' | 'unknown';
+    rttMs?: number;
+    bufferedAmountBytes?: number;
+    droppedEventsCount?: number;
+    totalEventsSent?: number;
+    totalEventsReceived?: number;
+    connectedAt?: number;
+    deviceName?: string;
+    platform?: string;
+}
+export type ControlCommandType = 'pause' | 'resume' | 'clear' | 'snapshot.request' | 'collector.enable' | 'collector.disable' | 'ping' | 'pong' | 'disconnect';
+export interface ControlCommand {
+    type: ControlCommandType;
+    collector?: string;
+    timestamp?: number;
+    payload?: unknown;
+}
+export interface RemoteMessage {
+    v: 1;
+    type: 'hello' | 'hello-ack' | 'event' | 'events-batch' | 'control' | 'ping' | 'pong';
+    payload?: unknown;
+    event?: CapDebugEvent;
+    events?: CapDebugEvent[];
+    command?: ControlCommand;
+    timestamp?: number;
+}

package/dist/remote/webrtc-transport.d.ts

@@ -0,0 +1,47 @@
+import type { CapDebugEvent } from '../types';
+import type { CapDebugTransport } from './transport';
+import type { ConnectionDiagnostics, ControlCommand, PairingConfig, TransportStatus } from './types';
+export declare class WebRTCTransport implements CapDebugTransport {
+    readonly id = "webrtc";
+    private pc;
+    private signaling;
+    private config;
+    private eventsChannel;
+    private controlChannel;
+    private status;
+    private buffer;
+    private eventListeners;
+    private controlListeners;
+    private statusListeners;
+    private diagnosticsListeners;
+    private pingTimer;
+    private statsTimer;
+    private rttMs;
+    private totalEventsSent;
+    private totalEventsReceived;
+    private connectedAt;
+    private remoteDeviceName;
+    private remotePlatform;
+    private diagnostics;
+    connect(config: PairingConfig): Promise<void>;
+    send(event: CapDebugEvent): void;
+    sendControl(command: ControlCommand): void;
+    disconnect(): void;
+    getStatus(): TransportStatus;
+    getDiagnostics(): ConnectionDiagnostics;
+    onEvent(callback: (event: CapDebugEvent) => void): () => void;
+    onControl(callback: (command: ControlCommand) => void): () => void;
+    onStatusChange(callback: (status: TransportStatus) => void): () => void;
+    onDiagnostics(callback: (diag: ConnectionDiagnostics) => void): () => void;
+    private handleSignalingMessage;
+    private initPeerConnection;
+    private startHandshakeAsInitiator;
+    private handleOffer;
+    private setupDataChannel;
+    private handleControlMessage;
+    private startTimers;
+    private stopTimers;
+    private queryWebRTCStats;
+    private setStatus;
+    private updateDiagnostics;
+}

package/ios/Sources/CapDebugPlugin/CapDebugPlugin.swift

@@ -20,14 +20,55 @@ public class CapDebugPlugin: CAPPlugin, CAPBridgedPlugin {
     private let monitorQueue = DispatchQueue(label: "com.capdebug.networkMonitor")
     private var lastKnownPath: NWPath?
 
+    private static weak var activeBridge: CAPBridgeProtocol?
+
     override public func load() {
         super.load()
+        Self.activeBridge = self.bridge
         networkMonitor.pathUpdateHandler = { [weak self] path in
             self?.lastKnownPath = path
         }
         networkMonitor.start(queue: monitorQueue)
     }
 
+    /// Emits a telemetry or debug event directly from Swift native code into CapDebug.
+    @objc public static func emit(
+        type: String,
+        message: String? = nil,
+        data: [String: Any]? = nil,
+        level: String = "info",
+        duration: Double = -1,
+        source: String = "native",
+        bridge: CAPBridgeProtocol? = nil
+    ) {
+        #if !DEBUG
+        // Zero-overhead guard: No-op in release/production builds
+        return
+        #else
+        guard let targetBridge = bridge ?? activeBridge else { return }
+
+        var payload: [String: Any] = [
+            "source": source,
+            "platform": "ios",
+            "type": type,
+            "level": level,
+            "timestamp": Int64(Date().timeIntervalSince1970 * 1000)
+        ]
+        if let message = message { payload["message"] = message }
+        if let data = data { payload["data"] = data }
+        if duration >= 0 { payload["duration"] = duration }
+
+        guard let jsonData = try? JSONSerialization.data(withJSONObject: payload, options: []),
+              let jsonString = String(data: jsonData, encoding: .utf8) else { return }
+
+        let js = "window.dispatchEvent(new CustomEvent('capdebug', { detail: \(jsonString) }));"
+
+        DispatchQueue.main.async {
+            targetBridge.webView?.evaluateJavaScript(js, completionHandler: nil)
+        }
+        #endif
+    }
+
     deinit {
         networkMonitor.cancel()
     }

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "capdebug",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Lightweight, embedded debug viewer and diagnostics plugin for Capacitor apps",
   "main": "dist/plugin.cjs.js",
   "module": "dist/plugin.mjs",
   "types": "dist/index.d.ts",
   "unpkg": "dist/plugin.js",
+  "bin": {
+    "capdebug": "./bin/capdebug.js"
+  },
   "files": [
     "dist/",
+    "bin/",
     "ios/",
     "android/",
     "CapDebug.podspec"
@@ -41,10 +45,10 @@
   "devDependencies": {
     "@capacitor/core": "^6.2.0",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^11.1.6",
     "@types/node": "^22.10.2",
     "jsdom": "^25.0.1",
     "rollup": "^4.28.1",
+    "rollup-plugin-esbuild": "^6.2.1",
     "tslib": "^2.8.1",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"