capdebug 0.1.0

package/CapDebug.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapDebug'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = 'https://github.com/capdebug/capdebug'
+  s.author = package['author']
+  s.source = { :git => 'https://github.com/capdebug/capdebug.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target  = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/README.md

@@ -0,0 +1,231 @@
+# CapDebug
+
+> Lightweight, embedded debug viewer and live diagnostics plugin for Capacitor applications.
+
+`capdebug` runs entirely inside your Capacitor WebView as an isolated Web Component with Shadow DOM. It displays a draggable floating debug pill on the screen that opens a mobile-first developer drawer with real-time logs, errors, network traffic, custom events, and native system diagnostics for iOS (Swift) and Android (Kotlin).
+
+---
+
+## Features
+
+- 🚀 **Zero UI Framework Dependencies**: Built purely with Web Components, Shadow DOM, and Vanilla CSS. Works seamlessly with React, Vue, Svelte, Angular, Solid, or Vanilla JS.
+- 🛡️ **Complete CSS Isolation**: Shadow DOM guarantees that the debug UI never conflicts with or inherits host application styles.
+- 📱 **Mobile-First Floating Trigger**: Draggable floating pill that automatically snaps to the left/right screen edge, persists coordinates in `localStorage`, and supports safe-area insets.
+- 📑 **Developer Drawer & Tabs**:
+  - **All**: Unified chronological event stream.
+  - **Console**: Intercepts `console.log`, `info`, `warn`, `error`, `debug`.
+  - **Errors**: Intercepts `window.onerror` and `unhandledrejection` with stack traces.
+  - **Events**: Custom app events dispatched via `CapDebug.emit()` or `CustomEvent('capdebug')`.
+  - **Native**: Native plugin events and bridge telemetry.
+  - **Device**: Live lazy-loaded diagnostics card for Device, Memory/Heap, App, WebView, and Network status.
+  - **Network**: Intercepts `fetch` requests with latency, status codes, and sanitized headers.
+  - **Bridge**: Capacitor plugin bridge activity collector.
+- 🔍 **Search & Level Filters**: Real-time filtering by search query (`type`, `message`, `data`) and severity levels (`ALL`, `DEBUG`, `INFO`, `WARN`, `ERROR`).
+- 🌳 **Interactive JSON Tree Viewer**: Collapsible nested objects/arrays, syntax coloring, individual value copying, and full payload JSON export.
+- 🔒 **Privacy & Sanitization by Default**: Recursively sanitizes data and masks sensitive keys (`authorization`, `cookie`, `password`, `token`, `secret`, `api_key`, `jwt`, `credit_card`, etc.) while safely handling circular references, BigInt, Symbols, and DOM nodes.
+- ⚡ **High Performance**: Circular FIFO ring buffer (default 500 events), incremental rendering, and `requestAnimationFrame` UI updates ensure zero lag in the host application.
+
+---
+
+## Installation
+
+```bash
+npm install -D capdebug
+npx cap sync
+```
+
+---
+
+## Quick Start
+
+Initialize CapDebug in your app's entry point:
+
+```ts
+import { CapDebug } from 'capdebug';
+
+// Mount the debug viewer
+CapDebug.mount();
+
+// Emit a test event
+CapDebug.emit({
+  type: 'app.booted',
+  message: 'Application started successfully',
+  data: { version: '1.0.0' }
+});
+```
+
+### Disabling in Production Builds (Recommended)
+
+To ensure zero bundle size overhead in production builds, dynamically import CapDebug only in development mode:
+
+```ts
+if (import.meta.env.DEV) {
+  const { CapDebug } = await import('capdebug');
+
+  CapDebug.mount({
+    console: true,
+    errors: true,
+    network: true,
+    native: true,
+  });
+}
+```
+
+---
+
+## Configuration Options
+
+Pass options to `CapDebug.mount(options)`:
+
+```ts
+CapDebug.mount({
+  button: true,             // Show floating trigger button (default: true)
+  position: 'right',        // Initial placement: 'right' | 'left' | { x, y } (default: 'right')
+  maxEvents: 500,           // Max events retained in ring buffer (default: 500)
+  console: true,            // Auto-capture console.log/info/warn/error/debug (default: true)
+  errors: true,             // Auto-capture window errors & unhandled promise rejections (default: true)
+  network: false,           // Auto-capture fetch API requests (default: false)
+  native: true,             // Enable iOS/Android native diagnostics bridge (default: true)
+  bridge: false,            // Enable bridge telemetry collector (default: false)
+  persistPosition: true,    // Save button screen position in localStorage (default: true)
+  defaultTab: 'all',        // Initial active tab: 'all' | 'console' | 'errors' | 'events' | 'device' | 'network' (default: 'all')
+  customMaskKeys: ['pin']   // Additional sensitive property keys to mask
+});
+```
+
+---
+
+## CustomEvent Event Bus
+
+CapDebug uses a standardized `CustomEvent('capdebug')` architecture as its core event bus. You can emit events from anywhere in your codebase without importing `capdebug`:
+
+```ts
+window.dispatchEvent(
+  new CustomEvent('capdebug', {
+    detail: {
+      source: 'web',
+      type: 'user.login',
+      level: 'info',
+      message: 'User logged in',
+      data: {
+        userId: 'usr_102',
+        role: 'admin',
+        token: 'secret_jwt_token' // Auto-masked as '********'
+      }
+    }
+  })
+);
+```
+
+Or use the convenient public helper:
+
+```ts
+import { CapDebug } from 'capdebug';
+
+CapDebug.emit({
+  type: 'cart.checkout',
+  level: 'info',
+  message: 'Checkout started',
+  duration: 180,
+  data: { total: 49.99, itemsCount: 3 }
+});
+```
+
+---
+
+## Public API Reference
+
+```ts
+// Lifecycle
+CapDebug.mount(options?: CapDebugOptions);
+CapDebug.unmount();
+
+// Visibility
+CapDebug.show();            // Open drawer
+CapDebug.hide();            // Close drawer
+CapDebug.toggle();          // Toggle drawer
+
+// Event & Buffer Control
+CapDebug.emit(event: CapDebugEventInput);
+CapDebug.clear();           // Clear all recorded events
+CapDebug.pause();           // Pause recording
+CapDebug.resume();          // Resume recording
+
+// Interception Collectors
+CapDebug.captureConsole();
+CapDebug.releaseConsole();
+
+CapDebug.captureErrors();
+CapDebug.releaseErrors();
+
+CapDebug.captureFetch({ body?: boolean });
+CapDebug.releaseFetch();
+
+CapDebug.observeEvent('online');
+CapDebug.observeEvent('visibilitychange');
+CapDebug.unobserveEvent('online');
+```
+
+---
+
+## Native Device Diagnostics
+
+When running in Capacitor iOS or Android (or web fallback), diagnostics are fetched on-demand when opening the **Device** tab or via programmatic calls:
+
+```ts
+import { CapDebug } from 'capdebug';
+
+// Device Info (manufacturer, model, OS version, architecture, emulator flag)
+const device = await CapDebug.native.getDeviceInfo();
+
+// Memory Info (app heap usage, total/max heap, system available memory)
+const memory = await CapDebug.native.getMemoryInfo();
+
+// WebView Info (user agent, webview version, debug mode)
+const webView = await CapDebug.native.getWebViewInfo();
+
+// App Info (bundle ID / package name, version, build number)
+const app = await CapDebug.native.getAppInfo();
+
+// Network Info (connection type: wifi/cellular/ethernet, metered status)
+const network = await CapDebug.native.getNetworkInfo();
+```
+
+---
+
+## Privacy & Security
+
+CapDebug is designed with privacy-first defaults:
+1. **Recursive Masking**: Passwords, tokens, cookies, auth headers, and API keys are automatically replaced with `'********'` in all data payloads and event views.
+2. **No Payload Leaks in Network Capture**: Network body capturing is disabled by default. If enabled via `{ network: { body: true } }`, sensitive fields inside JSON bodies are masked.
+3. **Permission Safety**: Native plugins only use standard, non-invasive system metrics (e.g. `NetworkCapabilities`, `ProcessInfo`, `mach_task_basic_info`). No fine location or private telephony permissions are requested.
+
+---
+
+## Running the Demo App
+
+The repository includes a complete Capacitor example app in the `example/` directory:
+
+```bash
+# Build capdebug package
+npm run build
+
+# Enter example directory and install
+cd example
+npm install
+npm run build
+
+# Run in browser
+npm run dev
+
+# Or sync to native mobile platforms
+npx cap add ios
+npx cap add android
+npx cap sync
+```
+
+---
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,63 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.12.0'
+    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.10.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.1'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "com.capdebug.plugin"
+    compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "0.1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.core:core-ktx:$androidxCoreVersion"
+    implementation "androidx.webkit:webkit:$androidxWebkitVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.22"
+    testImplementation "junit:junit:$junitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+</manifest>

package/android/src/main/java/com/capdebug/plugin/CapDebugPlugin.kt

@@ -0,0 +1,241 @@
+package com.capdebug.plugin
+
+import android.app.ActivityManager
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import android.content.pm.PackageInfo
+import android.content.pm.PackageManager
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.os.Build
+import android.webkit.WebView
+import androidx.webkit.WebViewCompat
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import java.util.Locale
+
+@CapacitorPlugin(name = "CapDebug")
+class CapDebugPlugin : Plugin() {
+
+    @PluginMethod
+    fun getDeviceInfo(call: PluginCall) {
+        try {
+            val ret = JSObject()
+            ret.put("manufacturer", Build.MANUFACTURER)
+            ret.put("model", Build.MODEL)
+            ret.put("device", Build.DEVICE)
+            ret.put("androidVersion", Build.VERSION.RELEASE)
+            ret.put("sdkVersion", Build.VERSION.SDK_INT)
+            ret.put("isEmulator", isEmulator())
+            ret.put("architecture", Build.SUPPORTED_ABIS.joinToString(", "))
+            ret.put("availableProcessors", Runtime.getRuntime().availableProcessors())
+            ret.put("platform", "android")
+            call.resolve(ret)
+        } catch (e: Exception) {
+            call.reject("Failed to get device info: ${e.message}", e)
+        }
+    }
+
+    @PluginMethod
+    fun getMemoryInfo(call: PluginCall) {
+        try {
+            val ret = JSObject()
+            val runtime = Runtime.getRuntime()
+            val totalHeap = runtime.totalMemory()
+            val freeHeap = runtime.freeMemory()
+            val maxHeap = runtime.maxMemory()
+            val usedHeap = totalHeap - freeHeap
+
+            ret.put("appMemoryUsage", usedHeap)
+            ret.put("appMemoryUsageFormatted", formatBytes(usedHeap))
+            ret.put("totalHeap", totalHeap)
+            ret.put("totalHeapFormatted", formatBytes(totalHeap))
+            ret.put("freeHeap", freeHeap)
+            ret.put("freeHeapFormatted", formatBytes(freeHeap))
+            ret.put("maxHeap", maxHeap)
+            ret.put("maxHeapFormatted", formatBytes(maxHeap))
+
+            val activityManager = context.getSystemService(Context.ACTIVITY_SERVICE) as? ActivityManager
+            if (activityManager != null) {
+                val memInfo = ActivityManager.MemoryInfo()
+                activityManager.getMemoryInfo(memInfo)
+
+                ret.put("systemAvailableMemory", memInfo.availMem)
+                ret.put("systemAvailableMemoryFormatted", formatBytes(memInfo.availMem))
+                ret.put("systemTotalMemory", memInfo.totalMem)
+                ret.put("systemTotalMemoryFormatted", formatBytes(memInfo.totalMem))
+                ret.put("lowMemory", memInfo.lowMemory)
+            }
+
+            call.resolve(ret)
+        } catch (e: Exception) {
+            call.reject("Failed to get memory info: ${e.message}", e)
+        }
+    }
+
+    @PluginMethod
+    fun getWebViewInfo(call: PluginCall) {
+        try {
+            val ret = JSObject()
+
+            var webViewVersion = "Unknown"
+            var webViewPackage = "Unknown"
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                val pkg = WebView.getCurrentWebViewPackage()
+                if (pkg != null) {
+                    webViewVersion = pkg.versionName ?: "Unknown"
+                    webViewPackage = pkg.packageName ?: "Unknown"
+                }
+            } else {
+                val pkg = WebViewCompat.getCurrentWebViewPackage(context)
+                if (pkg != null) {
+                    webViewVersion = pkg.versionName ?: "Unknown"
+                    webViewPackage = pkg.packageName ?: "Unknown"
+                }
+            }
+
+            val userAgent = try {
+                bridge?.webView?.settings?.userAgentString ?: "Unknown"
+            } catch (e: Exception) {
+                "Unknown"
+            }
+
+            val isDebuggable = (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+
+            ret.put("version", webViewVersion)
+            ret.put("packageName", webViewPackage)
+            ret.put("userAgent", userAgent)
+            ret.put("debugEnabled", isDebuggable)
+
+            call.resolve(ret)
+        } catch (e: Exception) {
+            call.reject("Failed to get webview info: ${e.message}", e)
+        }
+    }
+
+    @PluginMethod
+    fun getAppInfo(call: PluginCall) {
+        try {
+            val ret = JSObject()
+            val packageName = context.packageName
+            val packageManager = context.packageManager
+
+            var versionName = "Unknown"
+            var versionCode: Long = -1
+
+            try {
+                val packageInfo: PackageInfo = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                    packageManager.getPackageInfo(packageName, PackageManager.PackageInfoFlags.of(0))
+                } else {
+                    @Suppress("DEPRECATION")
+                    packageManager.getPackageInfo(packageName, 0)
+                }
+                versionName = packageInfo.versionName ?: "Unknown"
+                versionCode = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                    packageInfo.longVersionCode
+                } else {
+                    @Suppress("DEPRECATION")
+                    packageInfo.versionCode.toLong()
+                }
+            } catch (e: Exception) {
+                // ignore
+            }
+
+            val isDebuggable = (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+
+            ret.put("applicationId", packageName)
+            ret.put("versionName", versionName)
+            ret.put("version", versionName)
+            ret.put("versionCode", versionCode)
+            ret.put("buildType", if (isDebuggable) "debug" else "release")
+
+            call.resolve(ret)
+        } catch (e: Exception) {
+            call.reject("Failed to get app info: ${e.message}", e)
+        }
+    }
+
+    @PluginMethod
+    fun getNetworkInfo(call: PluginCall) {
+        try {
+            val ret = JSObject()
+            val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+
+            if (connectivityManager == null) {
+                ret.put("connected", false)
+                ret.put("connectionType", "none")
+                ret.put("metered", false)
+                call.resolve(ret)
+                return
+            }
+
+            val activeNetwork = connectivityManager.activeNetwork
+            val capabilities = connectivityManager.getNetworkCapabilities(activeNetwork)
+
+            if (capabilities == null) {
+                ret.put("connected", false)
+                ret.put("connectionType", "none")
+                ret.put("metered", false)
+                call.resolve(ret)
+                return
+            }
+
+            val isConnected = capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            val connectionType = when {
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> "wifi"
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> "cellular"
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> "ethernet"
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_VPN) -> "vpn"
+                capabilities.hasTransport(NetworkCapabilities.TRANSPORT_BLUETOOTH) -> "bluetooth"
+                else -> "other"
+            }
+
+            val isMetered = connectivityManager.isActiveNetworkMetered
+
+            ret.put("connected", isConnected)
+            ret.put("connectionType", connectionType)
+            ret.put("metered", isMetered)
+
+            call.resolve(ret)
+        } catch (e: Exception) {
+            call.reject("Failed to get network info: ${e.message}", e)
+        }
+    }
+
+    private fun isEmulator(): Boolean {
+        val finger = Build.FINGERPRINT.lowercase(Locale.ROOT)
+        val model = Build.MODEL.lowercase(Locale.ROOT)
+        val manufacturer = Build.MANUFACTURER.lowercase(Locale.ROOT)
+        val product = Build.PRODUCT.lowercase(Locale.ROOT)
+        val hardware = Build.HARDWARE.lowercase(Locale.ROOT)
+
+        return finger.startsWith("generic") ||
+                finger.startsWith("unknown") ||
+                model.contains("google_sdk") ||
+                model.contains("emulator") ||
+                model.contains("android sdk built for x86") ||
+                manufacturer.contains("genymotion") ||
+                hardware == "goldfish" ||
+                hardware == "ranchu" ||
+                product.contains("sdk_gphone") ||
+                product.contains("sdk") ||
+                product.contains("emulator")
+    }
+
+    private fun formatBytes(bytes: Long): String {
+        if (bytes <= 0) return "0 B"
+        val units = arrayOf("B", "KB", "MB", "GB", "TB")
+        val digitGroups = (Math.log10(bytes.toDouble()) / Math.log10(1024.0)).toInt()
+        val formatted = String.format(
+            Locale.US,
+            "%.2f %s",
+            bytes / Math.pow(1024.0, digitGroups.toDouble()),
+            units[digitGroups]
+        )
+        return formatted
+    }
+}

package/dist/collectors/bridge.collector.d.ts

@@ -0,0 +1,8 @@
+import type { CapDebugCollector } from '../types';
+export declare class BridgeCollector implements CapDebugCollector {
+    readonly id = "bridge";
+    private running;
+    start(): void;
+    stop(): void;
+    emitBridgeCall(pluginName: string, methodName: string, options?: unknown, duration?: number): void;
+}

package/dist/collectors/browser-event.collector.d.ts

@@ -0,0 +1,10 @@
+import type { CapDebugCollector } from '../types';
+export declare class BrowserEventCollector implements CapDebugCollector {
+    readonly id = "browser-event";
+    private running;
+    private observedEvents;
+    start(): void;
+    observe(eventName: string): void;
+    unobserve(eventName: string): void;
+    stop(): void;
+}

package/dist/collectors/collector.d.ts

@@ -0,0 +1,2 @@
+import type { CapDebugCollector } from '../types';
+export type { CapDebugCollector };

package/dist/collectors/console.collector.d.ts

@@ -0,0 +1,9 @@
+import type { CapDebugCollector } from '../types';
+export declare class ConsoleCollector implements CapDebugCollector {
+    readonly id = "console";
+    private running;
+    private originalMethods;
+    start(): void;
+    stop(): void;
+    private emitConsoleEvent;
+}

package/dist/collectors/custom-event.collector.d.ts

@@ -0,0 +1,11 @@
+import type { CapDebugCollector } from '../types';
+import type { CapDebugStore } from '../store';
+export declare class CustomEventCollector implements CapDebugCollector {
+    readonly id = "custom-event";
+    private store;
+    private running;
+    private handler;
+    constructor(store: CapDebugStore);
+    start(): void;
+    stop(): void;
+}

package/dist/collectors/error.collector.d.ts

@@ -0,0 +1,9 @@
+import type { CapDebugCollector } from '../types';
+export declare class ErrorCollector implements CapDebugCollector {
+    readonly id = "error";
+    private running;
+    private errorHandler;
+    private rejectionHandler;
+    start(): void;
+    stop(): void;
+}

package/dist/collectors/network.collector.d.ts

@@ -0,0 +1,12 @@
+import type { CapDebugCollector, NetworkCaptureOptions } from '../types';
+export declare class NetworkCollector implements CapDebugCollector {
+    readonly id = "network";
+    private running;
+    private originalFetch;
+    private options;
+    constructor(options?: NetworkCaptureOptions);
+    setOptions(options: NetworkCaptureOptions): void;
+    start(): void;
+    stop(): void;
+    private emitNetworkEvent;
+}

package/dist/definitions.d.ts

@@ -0,0 +1,9 @@
+import type { DeviceInfo, MemoryInfo, WebViewInfo, AppInfo, NetworkInfo } from './types';
+export interface CapDebugNativePlugin {
+    getDeviceInfo(): Promise<DeviceInfo>;
+    getMemoryInfo(): Promise<MemoryInfo>;
+    getWebViewInfo(): Promise<WebViewInfo>;
+    getAppInfo(): Promise<AppInfo>;
+    getNetworkInfo(): Promise<NetworkInfo>;
+}
+export declare const CapDebugNative: CapDebugNativePlugin;