capdebug 0.1.0 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@
 
 ## Features
 
+- 🌐 **QR-Based Remote WebRTC Debugging**: Run `npx capdebug` on your desktop, scan the terminal QR code with your phone camera, and stream all mobile debug events, logs, errors, and system metrics directly to your computer's browser in real-time over peer-to-peer WebRTC DataChannels.
 - 🚀 **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.
@@ -27,6 +28,35 @@
 
 ---
 
+## Remote Debugging (QR + WebRTC)
+
+CapDebug allows streaming your phone's debug session directly to your desktop browser without cables or cloud accounts:
+
+```bash
+# 1. On your computer terminal:
+npx capdebug
+```
+
+1. The CLI launches a local desktop viewer at `http://localhost:4783` and prints a scannable ANSI QR code.
+2. Point your phone's camera at the terminal to open the pairing URL.
+3. The phone connects via WebRTC DataChannel (Direct LAN / STUN) and streams all logs, errors, network calls, and native diagnostics to your desktop viewer in real-time.
+
+### Mobile Deep-Link Handling in Capacitor
+```ts
+import { App } from '@capacitor/app';
+import { CapDebug } from 'capdebug';
+
+if (import.meta.env.DEV) {
+  App.addListener('appUrlOpen', async ({ url }) => {
+    if (url.startsWith('capdebug://pair')) {
+      await CapDebug.handlePairingUrl(url);
+    }
+  });
+}
+```
+
+---
+
 ## Installation
 
 ```bash
@@ -168,7 +198,45 @@ CapDebug.unobserveEvent('online');
 
 ---
 
-## Native Device Diagnostics
+## Native Telemetry & Diagnostics
+
+### Emitting Telemetry from Swift & Kotlin
+
+`capdebug` includes static native helpers so native plugins, background workers, or services can emit debug events directly into the WebView's CapDebug event bus:
+
+#### iOS (Swift)
+```swift
+import CapDebug
+
+CapDebugPlugin.emit(
+    type: "native.video.compress",
+    message: "Video compression completed",
+    data: ["outputBitrate": 1500000, "codec": "h264"],
+    level: "info",
+    duration: 342.5 // ms
+)
+```
+
+#### Android (Kotlin)
+```kotlin
+import com.capdebug.plugin.CapDebugPlugin
+import com.getcapacitor.JSObject
+
+val data = JSObject().apply {
+    put("file", "recording.m4a")
+    put("format", "aac")
+}
+
+CapDebugPlugin.emit(
+    type: "native.audio.transcode",
+    message: "Audio transcode finished",
+    data: data,
+    level: "info",
+    duration: 180L // ms
+)
+```
+
+### Querying Native Device Diagnostics in TypeScript
 
 When running in Capacitor iOS or Android (or web fallback), diagnostics are fetched on-demand when opening the **Device** tab or via programmatic calls:
 

package/android/build/.transforms/105231053f5053e70f17f15178bed793/results.bin

@@ -0,0 +1 @@
+i/classes_global-synthetics

package/android/build/.transforms/7c2b02c40854250ff97be5e9e723091e/results.bin

@@ -0,0 +1 @@
+i/classes_dex

package/android/build/.transforms/ca1c0f6bb67b5238fd83a40c3a1c0ddd/results.bin

@@ -0,0 +1 @@
+o/classes

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/aapt/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.capdebug.plugin" >
+
+    <uses-sdk android:minSdkVersion="22" />
+
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+</manifest>

package/android/build/intermediates/aapt_friendly_merged_manifests/debug/aapt/output-metadata.json

@@ -0,0 +1,18 @@
+{
+  "version": 3,
+  "artifactType": {
+    "type": "AAPT_FRIENDLY_MERGED_MANIFESTS",
+    "kind": "Directory"
+  },
+  "applicationId": "com.capdebug.plugin",
+  "variantName": "debug",
+  "elements": [
+    {
+      "type": "SINGLE",
+      "filters": [],
+      "attributes": [],
+      "outputFile": "AndroidManifest.xml"
+    }
+  ],
+  "elementType": "File"
+}

package/android/build/intermediates/aar_metadata/debug/aar-metadata.properties

@@ -0,0 +1,6 @@
+aarFormatVersion=1.0
+aarMetadataVersion=1.0
+minCompileSdk=1
+minCompileSdkExtension=0
+minAndroidGradlePluginVersion=1.0.0
+coreLibraryDesugaringEnabled=false

package/android/build/intermediates/annotation_processor_list/debug/annotationProcessors.json

@@ -0,0 +1 @@
+{}

package/android/build/intermediates/incremental/debug/packageDebugResources/compile-file-map.properties

@@ -0,0 +1 @@
+#Tue Sep 15 23:01:42 TRT 2026

package/android/build/intermediates/incremental/debug/packageDebugResources/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="main" generated-set="main$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="debug" generated-set="debug$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/debug/res"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated$Generated" generated="true" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/build/generated/res/resValues/debug"/></dataSet><dataSet aapt-namespace="http://schemas.android.com/apk/res-auto" config="generated" generated-set="generated$Generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/build/generated/res/resValues/debug"/></dataSet><mergedItems/></merger>

package/android/build/intermediates/incremental/mergeDebugJniLibFolders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/jniLibs"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/debug/jniLibs"/></dataSet></merger>

package/android/build/intermediates/incremental/mergeDebugShaders/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/shaders"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/debug/shaders"/></dataSet></merger>

package/android/build/intermediates/incremental/packageDebugAssets/merger.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/assets"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/debug/assets"/></dataSet><dataSet config="generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/build/intermediates/shader_assets/debug/out"/></dataSet></merger>

package/android/build/intermediates/local_only_symbol_list/debug/R-def.txt

@@ -0,0 +1,2 @@
+R_DEF: Internal format may change without notice
+local

package/android/build/intermediates/manifest_merge_blame_file/debug/manifest-merger-blame-debug-report.txt

@@ -0,0 +1,11 @@
+1<?xml version="1.0" encoding="utf-8"?>
+2<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+3    package="com.capdebug.plugin" >
+4
+5    <uses-sdk android:minSdkVersion="22" />
+6
+7    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+7-->/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:2:5-79
+7-->/Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:2:22-76
+8
+9</manifest>

package/android/build/intermediates/merged_manifest/debug/AndroidManifest.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.capdebug.plugin" >
+
+    <uses-sdk android:minSdkVersion="22" />
+
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+</manifest>

package/android/build/intermediates/navigation_json/debug/navigation.json

@@ -0,0 +1 @@
+[]

package/android/build/intermediates/symbol_list_with_package_name/debug/package-aware-r.txt

@@ -0,0 +1 @@
+com.capdebug.plugin

package/android/build/kotlin/compileDebugKotlin/cacheable/caches-jvm/lookups/counters.tab

@@ -0,0 +1,2 @@
+1
+0

package/android/build/outputs/logs/manifest-merger-debug-report.txt

@@ -0,0 +1,20 @@
+-- Merging decision tree log ---
+manifest
+ADDED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:1:1-3:12
+INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:1:1-3:12
+	package
+		INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml
+	xmlns:android
+		ADDED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:1:11-69
+uses-permission#android.permission.ACCESS_NETWORK_STATE
+ADDED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:2:5-79
+	android:name
+		ADDED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml:2:22-76
+uses-sdk
+INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml reason: use-sdk injection requested
+INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml
+INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml
+	android:targetSdkVersion
+		INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml
+	android:minSdkVersion
+		INJECTED from /Users/ahmet/projects/capdebug/example/node_modules/capdebug/android/src/main/AndroidManifest.xml

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

@@ -20,6 +20,60 @@ import java.util.Locale
 @CapacitorPlugin(name = "CapDebug")
 class CapDebugPlugin : Plugin() {
 
+    override fun load() {
+        super.load()
+        activeBridge = bridge
+    }
+
+    companion object {
+        private var activeBridge: com.getcapacitor.Bridge? = null
+
+        /**
+         * Emits a telemetry or debug event directly from Android native code into CapDebug.
+         */
+        @JvmStatic
+        @JvmOverloads
+        fun emit(
+            type: String,
+            message: String? = null,
+            data: JSObject? = null,
+            level: String = "info",
+            duration: Long? = null,
+            source: String = "native",
+            bridge: com.getcapacitor.Bridge? = null
+        ) {
+            val targetBridge = bridge ?: activeBridge ?: return
+
+            // Zero-overhead guard: No-op in production release builds
+            val isDebuggable = try {
+                val context = targetBridge.context
+                (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+            } catch (e: Exception) {
+                false
+            }
+
+            if (!isDebuggable) {
+                return
+            }
+
+            val payload = JSObject().apply {
+                put("source", source)
+                put("platform", "android")
+                put("type", type)
+                put("level", level)
+                message?.let { put("message", it) }
+                put("timestamp", System.currentTimeMillis())
+                data?.let { put("data", it) }
+                duration?.let { put("duration", it) }
+            }
+
+            val js = "window.dispatchEvent(new CustomEvent('capdebug', { detail: $payload }));"
+            targetBridge.webView?.post {
+                targetBridge.webView?.evaluateJavascript(js, null)
+            }
+        }
+    }
+
     @PluginMethod
     fun getDeviceInfo(call: PluginCall) {
         try {

package/bin/capdebug.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require('../dist/cli.js');
+
+runCli().catch((err) => {
+  console.error('[CapDebug CLI Error]:', err);
+  process.exit(1);
+});

package/dist/capacitor/deep-link.d.ts

@@ -0,0 +1,4 @@
+import { type ParsedPairingInfo } from '../remote/pairing';
+export declare class DeepLinkHandler {
+    static parse(url: string): ParsedPairingInfo | null;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli/qr.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Zero-dependency QR Code matrix generator and terminal ANSI renderer.
+ * Encodes Byte Mode URLs and renders compact Unicode half-block characters.
+ */
+export declare class TerminalQRCode {
+    /**
+     * Generates a 2D boolean grid (true = dark/black, false = light/white) for the given text.
+     */
+    static generateMatrix(text: string): boolean[][];
+    /**
+     * Renders the matrix to terminal string using ANSI half-block characters (▀, ▄, █).
+     * 2 vertical rows are packed into 1 line of terminal output for high compactness.
+     */
+    static renderToString(text: string): string;
+}

package/dist/cli/server.d.ts

@@ -0,0 +1,34 @@
+import * as http from 'http';
+import type { PairingSession } from '../remote/types';
+export interface ServerSessionInfo {
+    session: PairingSession;
+    secret: string;
+    subscribers: Set<http.ServerResponse>;
+    peerJoined: boolean;
+}
+export declare class CapDebugCliServer {
+    private server;
+    private sessions;
+    private port;
+    private host;
+    constructor(options?: {
+        port?: number;
+        host?: string;
+    });
+    getLanIp(): string;
+    getLocalViewerUrl(): string;
+    getMobilePairingUrl(sessionId: string, secret: string): string;
+    createSession(): {
+        session: PairingSession;
+        secret: string;
+    };
+    getSession(id: string): ServerSessionInfo | undefined;
+    start(): Promise<{
+        port: number;
+        lanIp: string;
+    }>;
+    stop(): Promise<void>;
+    private handleRequest;
+    private broadcast;
+    private readJsonBody;
+}