react-native-debug-toolkit 3.3.4 → 3.5.0

package/README.md

@@ -63,8 +63,8 @@ Run the app in dev mode, then tap `DBG`.
 Start the desktop daemon:
 
 ```bash
-npm exec debug-toolkit --daemon-only
-# or: npx debug-toolkit --daemon-only
+npm exec -- debug-toolkit --daemon-only
+# or: npx react-native-debug-toolkit --daemon-only
 ```
 
 Open the Web Console:
@@ -77,45 +77,6 @@ In the app, open Debug Panel -> `DevConnect` -> `Send Once` or `Start Live Sync`
 
 DevConnect auto-detects simulator/emulator and uses local host settings automatically. On real devices, enter your computer IP to connect.
 
-### Embedded Debug Bundle
-
-Debug builds need an embedded JS bundle for cold start when Metro is off.
-
-Bare React Native:
-
-```bash
-npx debug-toolkit setup-bundle
-git diff
-git commit -am "chore: enable debug bundle embedding"
-```
-
-Expo dev-client:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
-    ]
-  }
-}
-```
-
-Verify built artifacts:
-
-```bash
-npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
-npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
-```
-
-After setup, build machines run normal Xcode, Gradle, React Native, or EAS commands. Do not run a separate mutation command on every build.
-
-For Remote JS Bundle, run Metro on your computer, enter computer IP and Metro port in `DevConnect`, then tap `Use Metro Bundle`. DevConnect persists the host and hot-reloads from Metro. Use **Reset** to go back to the embedded bundle.
-
-> **Debug builds only.** Metro host switching works in Debug builds. Release builds load the embedded bundle and the controls are disabled (`release: disabled` badge).
-
-**iOS — no AppDelegate changes required.** On install, DevConnect hooks `RCTBundleURLProvider` so the app **cold-starts from the embedded `main.jsbundle`** and only connects to Metro after you apply a host in the panel (fixes Expo `.expo/.virtual-metro-entry` red screens when Metro is off).
-
 The IP and ports are persisted through AsyncStorage when installed, or through the native module after rebuild.
 
 QR scan is optional. Install `react-native-camera-kit` or `expo-camera` in the app to enable the scan button. The app must request camera permission before scanning.
@@ -145,9 +106,9 @@ The daemon stores logs at:
 Custom store path:
 
 ```bash
-npm exec debug-toolkit --daemon-only --store /path/to/devices.json
-# or: npx debug-toolkit --daemon-only --store /path/to/devices.json
-DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npm exec debug-toolkit --daemon-only
+npm exec -- debug-toolkit --daemon-only --store /path/to/devices.json
+# or: npx react-native-debug-toolkit --daemon-only --store /path/to/devices.json
+DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npm exec -- debug-toolkit --daemon-only
 ```
 
 ## Read Logs With HTTP
@@ -189,8 +150,8 @@ GET    /console
 ## Use MCP
 
 ```bash
-claude mcp add debug-toolkit -- npm exec debug-toolkit
-# or: claude mcp add debug-toolkit -- npx debug-toolkit
+claude mcp add debug-toolkit -- npm exec -- debug-toolkit
+# or: claude mcp add debug-toolkit -- npx react-native-debug-toolkit
 ```
 
 Tools:
@@ -210,6 +171,46 @@ Disable features:
 </DebugView>
 ```
 
+Custom tabs:
+
+```tsx
+import {
+  DebugView,
+  createDebugTab,
+  type DebugFeatureRenderProps,
+} from 'react-native-debug-toolkit';
+
+type UserSnapshot = {
+  id?: string;
+  role?: string;
+};
+
+function UserDebugTab({ snapshot }: DebugFeatureRenderProps<UserSnapshot>) {
+  return (
+    <View>
+      <Text>User ID: {snapshot.id ?? '-'}</Text>
+      <Text>Role: {snapshot.role ?? '-'}</Text>
+    </View>
+  );
+}
+
+const userDebugTab = createDebugTab<UserSnapshot>({
+  name: 'user',
+  label: 'User',
+  getSnapshot: () => ({
+    id: authStore.user?.id,
+    role: authStore.user?.role,
+  }),
+  render: UserDebugTab,
+});
+
+<DebugView customFeatures={[userDebugTab]}>
+  <AppContent />
+</DebugView>;
+```
+
+Each custom feature becomes a panel tab. `name` is the stable tab id, `label` is shown in the tab bar, `getSnapshot` provides tab data, and `render` controls the UI. Add `subscribe` when the tab should refresh after external state changes.
+
 Navigation tracking:
 
 ```tsx
@@ -239,6 +240,7 @@ addTrackLog({ eventName: 'button_click' });
 - `DebugView`
 - `DebugToolkit`
 - `initializeDebugToolkit`
+- `createDebugTab`
 - `createDebugDeviceReport`
 - `checkDaemonConnection`
 - `reportDebugDeviceToDaemon`

package/README.zh-CN.md

@@ -63,8 +63,8 @@ export function App() {
 启动桌面 daemon：
 
 ```bash
-npm exec debug-toolkit --daemon-only
-# 或：npx debug-toolkit --daemon-only
+npm exec -- debug-toolkit --daemon-only
+# 或：npx react-native-debug-toolkit --daemon-only
 ```
 
 打开 Web Console：
@@ -77,45 +77,6 @@ App 内打开 Debug Panel -> `DevConnect` -> `Send Once` 或 `Start Live Sync`
 
 DevConnect 自动识别模拟器/真机，模拟器下自动使用本机 Metro/daemon 地址。真机需输入电脑 IP 地址。
 
-### Debug 包内置 Bundle
-
-Debug 包要在 Metro 关闭时冷启动，必须内置 JS bundle。
-
-Bare React Native:
-
-```bash
-npx debug-toolkit setup-bundle
-git diff
-git commit -am "chore: enable debug bundle embedding"
-```
-
-Expo dev-client:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
-    ]
-  }
-}
-```
-
-验证产物：
-
-```bash
-npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
-npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
-```
-
-setup 后配置进仓库，打包机继续跑正常 Xcode、Gradle、React Native 或 EAS 命令。不要每次打包再跑额外修改命令。
-
-Remote JS Bundle：先在电脑启动 Metro，在 `DevConnect` 输入电脑 IP 和 Metro 端口，然后点 `Use Metro Bundle`。DevConnect 会持久化 host 并从 Metro 热重载。点 **Reset** 可回到内置 bundle。
-
-> **仅 Debug 包可用。** Release 包控件会显示 `release: disabled` 并禁用。
-
-**iOS — 无需改 AppDelegate。** 安装本库后会 hook `RCTBundleURLProvider`：**未配置 IP 时冷启动走内置 `main.jsbundle`**，只有在面板里应用 host 后才连 Metro（可避免 Metro 未开时的 `.expo/.virtual-metro-entry` 红屏）。
-
 IP 和端口会通过 AsyncStorage 持久化；如果没装 AsyncStorage，则在重建后通过本库原生模块持久化。
 
 扫码是可选能力。App 安装 `react-native-camera-kit` 或 `expo-camera` 后，DevConnect 才显示扫码按钮。App 仍需自己配置相机权限文案，并在使用扫码前申请相机权限。
@@ -145,9 +106,9 @@ daemon 默认日志文件：
 自定义存储路径：
 
 ```bash
-npm exec debug-toolkit --daemon-only --store /path/to/devices.json
-# 或：npx debug-toolkit --daemon-only --store /path/to/devices.json
-DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npm exec debug-toolkit --daemon-only
+npm exec -- debug-toolkit --daemon-only --store /path/to/devices.json
+# 或：npx react-native-debug-toolkit --daemon-only --store /path/to/devices.json
+DEBUG_TOOLKIT_DAEMON_STORE=/path/to/devices.json npm exec -- debug-toolkit --daemon-only
 ```
 
 ## 用 HTTP 读取日志
@@ -189,8 +150,8 @@ GET    /console
 ## 使用 MCP
 
 ```bash
-claude mcp add debug-toolkit -- npm exec debug-toolkit
-# 或：claude mcp add debug-toolkit -- npx debug-toolkit
+claude mcp add debug-toolkit -- npm exec -- debug-toolkit
+# 或：claude mcp add debug-toolkit -- npx react-native-debug-toolkit
 ```
 
 工具：
@@ -210,6 +171,46 @@ claude mcp add debug-toolkit -- npm exec debug-toolkit
 </DebugView>
 ```
 
+自定义 Tab：
+
+```tsx
+import {
+  DebugView,
+  createDebugTab,
+  type DebugFeatureRenderProps,
+} from 'react-native-debug-toolkit';
+
+type UserSnapshot = {
+  id?: string;
+  role?: string;
+};
+
+function UserDebugTab({ snapshot }: DebugFeatureRenderProps<UserSnapshot>) {
+  return (
+    <View>
+      <Text>User ID: {snapshot.id ?? '-'}</Text>
+      <Text>Role: {snapshot.role ?? '-'}</Text>
+    </View>
+  );
+}
+
+const userDebugTab = createDebugTab<UserSnapshot>({
+  name: 'user',
+  label: 'User',
+  getSnapshot: () => ({
+    id: authStore.user?.id,
+    role: authStore.user?.role,
+  }),
+  render: UserDebugTab,
+});
+
+<DebugView customFeatures={[userDebugTab]}>
+  <AppContent />
+</DebugView>;
+```
+
+每个自定义 feature 都会变成一个面板 Tab。`name` 是稳定 Tab id，`label` 显示在 Tab 栏，`getSnapshot` 提供展示数据，`render` 控制展示 UI。外部状态变化后需要自动刷新时，给它加 `subscribe`。
+
 导航追踪：
 
 ```tsx
@@ -239,6 +240,7 @@ addTrackLog({ eventName: 'button_click' });
 - `DebugView`
 - `DebugToolkit`
 - `initializeDebugToolkit`
+- `createDebugTab`
 - `createDebugDeviceReport`
 - `checkDaemonConnection`
 - `reportDebugDeviceToDaemon`

package/android/src/main/java/com/reactnativedebugtoolkit/DebugToolkitDevConnectModule.java

@@ -8,16 +8,11 @@ import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
 import com.reactnativedebugtoolkit.BuildConfig;
-import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
 import com.facebook.react.bridge.ReactContextBaseJavaModule;
 import com.facebook.react.bridge.ReactMethod;
-import com.facebook.react.bridge.UiThreadUtil;
-import com.facebook.react.bridge.WritableMap;
 
-import java.lang.reflect.Method;
-import java.lang.reflect.Proxy;
 import java.net.Inet4Address;
 import java.net.InetAddress;
 import java.net.NetworkInterface;
@@ -25,11 +20,6 @@ import java.util.Enumeration;
 
 public class DebugToolkitDevConnectModule extends ReactContextBaseJavaModule {
   private static final String MODULE_NAME = "DebugToolkitDevConnect";
-  private static final String BUNDLE_ROOT = "index";
-  private static final String DEBUG_SERVER_HOST_KEY = "debug_http_host";
-  private static final String KOTLIN_FUNCTION1_CLASS = "kotlin.jvm.functions.Function1";
-  private static final String APPLY_RELOAD_REASON = "DebugToolkit DevConnect Metro host changed";
-  private static final String RESET_RELOAD_REASON = "DebugToolkit DevConnect Metro host reset";
 
   public DebugToolkitDevConnectModule(ReactApplicationContext reactContext) {
     super(reactContext);
@@ -45,183 +35,6 @@ public class DebugToolkitDevConnectModule extends ReactContextBaseJavaModule {
     return PreferenceManager.getDefaultSharedPreferences(getReactApplicationContext());
   }
 
-  @Nullable
-  private Object callGetter(Object target, String methodName) {
-    try {
-      Method method = target.getClass().getMethod(methodName);
-      return method.invoke(target);
-    } catch (Exception ignored) {
-      return null;
-    }
-  }
-
-  private void setDebugServerHost(@Nullable Object devSupportManager, String hostPort) throws Exception {
-    if (devSupportManager == null) {
-      return;
-    }
-
-    Object devSettings = callGetter(devSupportManager, "getDevSettings");
-    Object packagerConnectionSettings = devSettings == null
-        ? null
-        : callGetter(devSettings, "getPackagerConnectionSettings");
-    if (packagerConnectionSettings == null) {
-      return;
-    }
-
-    Method setter = packagerConnectionSettings.getClass().getMethod("setDebugServerHost", String.class);
-    setter.invoke(packagerConnectionSettings, hostPort);
-  }
-
-  private boolean setReactHostBundleSource(Object reactHost, String hostPort) throws Exception {
-    if (hostPort.length() == 0) {
-      return false;
-    }
-
-    try {
-      Class<?> function1Class = Class.forName(KOTLIN_FUNCTION1_CLASS);
-      Method setBundleSourceMethod = reactHost.getClass().getMethod(
-          "setBundleSource",
-          String.class,
-          String.class,
-          function1Class
-      );
-      Object queryMapper = Proxy.newProxyInstance(
-          function1Class.getClassLoader(),
-          new Class<?>[] { function1Class },
-          (proxy, method, args) -> {
-            String methodName = method.getName();
-            if ("invoke".equals(methodName)) {
-              return args != null && args.length > 0 ? args[0] : null;
-            }
-            if ("toString".equals(methodName)) {
-              return "DebugToolkitIdentityQueryMapper";
-            }
-            if ("hashCode".equals(methodName)) {
-              return System.identityHashCode(proxy);
-            }
-            if ("equals".equals(methodName)) {
-              return proxy == (args != null && args.length > 0 ? args[0] : null);
-            }
-            return null;
-          }
-      );
-      setBundleSourceMethod.invoke(reactHost, hostPort, BUNDLE_ROOT, queryMapper);
-      return true;
-    } catch (ClassNotFoundException | NoSuchMethodException ignored) {
-      return false;
-    }
-  }
-
-  private boolean triggerDevSupportReload(
-      @Nullable Object devSupportManager,
-      String hostPort
-  ) throws Exception {
-    if (devSupportManager == null) {
-      return false;
-    }
-
-    Object enabled = callGetter(devSupportManager, "getDevSupportEnabled");
-    if (enabled instanceof Boolean && !((Boolean) enabled)) {
-      return false;
-    }
-
-    setDebugServerHost(devSupportManager, hostPort);
-    Method reloadMethod = devSupportManager.getClass().getMethod("handleReloadJS");
-    reloadMethod.invoke(devSupportManager);
-    return true;
-  }
-
-  private boolean reloadFromReactHost(
-      Context applicationContext,
-      String reason,
-      String hostPort
-  ) throws Exception {
-    Object reactHost = callGetter(applicationContext, "getReactHost");
-    if (reactHost == null) {
-      return false;
-    }
-
-    if (setReactHostBundleSource(reactHost, hostPort)) {
-      return true;
-    }
-
-    if (triggerDevSupportReload(callGetter(reactHost, "getDevSupportManager"), hostPort)) {
-      return true;
-    }
-
-    Method reloadMethod = reactHost.getClass().getMethod("reload", String.class);
-    reloadMethod.invoke(reactHost, reason);
-    return true;
-  }
-
-  private boolean reloadFromReactNativeHost(Context applicationContext, String hostPort) throws Exception {
-    Object reactNativeHost = callGetter(applicationContext, "getReactNativeHost");
-    Object instanceManager = reactNativeHost == null
-        ? null
-        : callGetter(reactNativeHost, "getReactInstanceManager");
-    Object devSupportManager = instanceManager == null
-        ? null
-        : callGetter(instanceManager, "getDevSupportManager");
-    return triggerDevSupportReload(devSupportManager, hostPort);
-  }
-
-  private void resolveAfterReload(
-      String reason,
-      @Nullable WritableMap result,
-      String hostPort,
-      Promise promise
-  ) {
-    UiThreadUtil.runOnUiThread(() -> {
-      try {
-        Context applicationContext = getReactApplicationContext().getApplicationContext();
-        boolean reloaded = reloadFromReactHost(applicationContext, reason, hostPort)
-            || reloadFromReactNativeHost(applicationContext, hostPort);
-        if (!reloaded) {
-          promise.reject("reload_unavailable", "Unable to trigger React Native reload after updating Metro host.");
-          return;
-        }
-        promise.resolve(result);
-      } catch (Exception error) {
-        promise.reject("reload_failed", "Unable to trigger React Native reload after updating Metro host.", error);
-      }
-    });
-  }
-
-  @ReactMethod
-  public void getMetroHost(Promise promise) {
-    @Nullable String host = getPreferences().getString(DEBUG_SERVER_HOST_KEY, null);
-    promise.resolve(host);
-  }
-
-  @ReactMethod
-  public void applyMetroHost(String hostPort, Promise promise) {
-    if (hostPort == null || hostPort.length() == 0) {
-      promise.reject("invalid_host", "Metro host cannot be empty.");
-      return;
-    }
-
-    boolean stored = getPreferences().edit().putString(DEBUG_SERVER_HOST_KEY, hostPort).commit();
-    if (!stored) {
-      promise.reject("storage_failed", "Unable to persist Metro host.");
-      return;
-    }
-
-    WritableMap result = Arguments.createMap();
-    result.putString("hostPort", hostPort);
-    resolveAfterReload(APPLY_RELOAD_REASON, result, hostPort, promise);
-  }
-
-  @ReactMethod
-  public void resetMetroHost(Promise promise) {
-    boolean stored = getPreferences().edit().remove(DEBUG_SERVER_HOST_KEY).commit();
-    if (!stored) {
-      promise.reject("storage_failed", "Unable to reset Metro host.");
-      return;
-    }
-
-    resolveAfterReload(RESET_RELOAD_REASON, null, "", promise);
-  }
-
   @ReactMethod
   public void getPreference(String key, Promise promise) {
     @Nullable String value = getPreferences().getString(key, null);

package/bin/debug-toolkit.js

@@ -27,16 +27,9 @@ function hasHelpFlag(args) {
 function printHelp() {
   process.stderr.write(
     'Usage: debug-toolkit [--host 0.0.0.0] [--port 3799] [--token dev-token] [--store ~/.react-native-debug-toolkit/daemon-devices.json] [--daemon-only]\n'
-  + '       debug-toolkit setup-bundle [--platform ios|android] [--undo] [--check] [--ios-target <name>]\n'
-  + '       debug-toolkit doctor-bundle --platform ios --app <path-to.app>\n'
-  + '       debug-toolkit doctor-bundle --platform android --apk <path-to.apk>\n'
   + '\n'
   + 'Starts the debug toolkit: daemon (HTTP + Web Console) and MCP stdio server.\n'
   + '\n'
-  + 'Commands:\n'
-  + '  setup-bundle    Persistently configure host app debug builds to embed JS bundle\n'
-  + '  doctor-bundle   Verify source config or built app package contains embedded bundle\n'
-  + '\n'
   + 'Daemon options:\n'
   + '  --host <addr>   Host to bind (default: 0.0.0.0)\n'
   + '  --port <port>   Port to bind (default: 3799)\n'
@@ -64,15 +57,6 @@ async function main() {
     return;
   }
 
-  if (['setup-bundle', 'doctor-bundle', 'embed'].includes(args[0])) {
-    const { runBundleCli } = require('../scripts/bundle/cli');
-    const code = await runBundleCli(args);
-    if (code !== 0) {
-      process.exitCode = code;
-    }
-    return;
-  }
-
   const host = readOption(args, '--host', process.env.DEBUG_TOOLKIT_DAEMON_HOST || DEFAULT_HOST);
   const port = Number(readOption(args, '--port', process.env.DEBUG_TOOLKIT_DAEMON_PORT || DEFAULT_PORT));
   const token = readOption(args, '--token', process.env.DEBUG_TOOLKIT_DAEMON_TOKEN || '');

package/ios/DebugToolkitDevConnect.h

@@ -2,16 +2,4 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- Returns a Metro bundle URL when the user has applied a host via DevConnect; otherwise nil.
-
- Zero-config: installing this pod hooks RCTBundleURLProvider so cold start uses the embedded
- main.jsbundle until DevConnect applies a host. You do not need to change AppDelegate.
-
- Optional override for custom bundleURL() implementations:
-
-     if let metro = DebugToolkitMetroBundleURL() { return metro }
- */
-FOUNDATION_EXPORT NSURL * _Nullable DebugToolkitMetroBundleURL(void);
-
 NS_ASSUME_NONNULL_END