improve quick start

.vscode/settings.json

@@ -43,5 +43,8 @@
     },
     "cSpell.enableFiletypes": [
         "mdx"
-    ]
+    ],
+    "[mdx]": {
+        "editor.wordWrap": "on"
+    }
 }

docs/tango/daemon/_category_.yml

@@ -1,6 +1,3 @@
 position: 2
 label: 'Direct Connection'
 collapsed: false
-link:
-  type: generated-index
-  title: 'Direct Connection'

docs/tango/daemon/credential-store.mdx

@@ -5,7 +5,7 @@ sidebar_position: 4
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# Create credential store
+# Credential store
 
 Directly connecting to devices requires authentication. The authentication process uses [RSA algorithm](<https://en.wikipedia.org/wiki/RSA_(cryptosystem)>), except it uses a custom public key format.
 

docs/tango/daemon/custom-connection.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Create custom connection
+# Custom connection
 
 :::note
 

docs/tango/daemon/index.mdx

@@ -0,0 +1,19 @@
+# Direct Connection
+
+In Direct Connection Mode, Tango connects to the ADB daemon running on Android devices directly. This is the lowest-level connection mode, Tango controls all the steps, including authentication, message encoding and decoding, and connection management.
+
+The `AdbDaemonTransport` class from `@yume-chan/adb` implements this mode.
+
+To support different runtime and connection method, `AdbDaemonTransport` accepts an `AdbDaemonConnection` object for communicating with the device, and an `AdbCredentialStore` object for managing client certificates.
+
+Here are the basic steps to establish a connection in Direct Connection Mode:
+
+1. Create an `AdbDaemonConnection` object for the runtime and connection method you want to use.
+2. Create an `AdnCredentialStore` object for the runtime.
+3. Pass the connection and credential store to `AdbDaemonTransport` to authenticate and initialize the connection.
+4. Use the `AdbDaemonTransport` object to create an `Adb` instance.
+5. Use the `Adb` instance to send commands to the device.
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

docs/tango/daemon/tcp/_category_.yml

@@ -1,6 +1,6 @@
 position: 2
-label: 'Create TCP connection'
+label: 'TCP connection'
 collapsed: false
 link:
   type: generated-index
-  title: 'Create TCP connection'
+  title: 'TCP connection'

docs/tango/daemon/tcp/enable.mdx

@@ -2,22 +2,27 @@
 sidebar_position: 1
 ---
 
-# Enable ADB over WiFi
+# Enable ADB over Wi-Fi
 
-ADB over WiFi allows you to connect to your device wirelessly. This is useful when you want to connect to your device without using a USB cable, or if you want to connect multiple devices to the same computer.
+ADB over Wi-Fi allows you to connect to your device wirelessly. This is useful when you want to connect to your device without using a USB cable, or if you want to connect multiple devices to the same computer.
 
 ## Android 11 and above
 
-Android 11 adds a new Wireless Debugging feature in Developer Options, which allows you to enable ADB over WiFi without using a USB cable.
+Android 11 added a Wireless Debugging feature in Developer Options, which allows you connect to the device wirelessly.
 
-However, Wireless Debugging is different from ADB over WiFi, and has the following limitations:
+However, Wireless Debugging is different from ADB over Wi-Fi, and not supported by Tango.
 
-* It chooses a random port to listen at, and the port number changes every time the device is restarted.
-* Client certificate can only be trusted using the new ADB pairing feature, which is not supported by Tango.
+Technical details:
+
+* Wireless Debugging uses mDNS to automatically discover devices in the same network.
+  * It's not implemented on Windows
+  * Some Linux distributions compiles ADB themselves, and doesn't include mDNS support.
+* Wireless Debugging uses TLS to validate the client and encrypt the connection.
+* Wireless Debugging adds trusted client certificates using the new ADB pairing feature.
 
 ## Rooted devices
 
-On rooted devices, ADB over WiFi can be enabled by running the following command on the device:
+On rooted devices, ADB over Wi-Fi can be enabled by running the following command on the device:
 
 ```sh
 su
@@ -30,16 +35,16 @@ start adbd
 
 ## Other devices
 
-On non-rooted devices with Android 10 and below, enabling ADB over WiFi requires first connecting the device using a USB cable.
+On non-rooted devices with Android 10 and below, enabling ADB over Wi-Fi requires first connecting the device using a USB cable.
 
-- To enable ADB over WiFi using Google ADB, run the following command in a terminal:
+- To enable ADB over Wi-Fi using Google ADB, run the following command in a terminal:
 
   ```sh
   adb tcpip 5555
   ```
 
   `5555` is the port ADB daemon will listen at, and can be freely changed.
 
-- To enable ADB over WiFI using Tango, use the [`tcpip` command](../../../api/tcpip.mdx).
+- To enable ADB over Wi-Fi using Tango, use the [`tcpip` command](../../../api/tcpip.mdx).
 
-When device is restarted, ADB over WiFi will be disabled. To re-enable it, connect the device using a USB cable and follow the steps above again.
+When device is restarted, ADB over Wi-Fi will be disabled. To re-enable it, connect the device using a USB cable and follow the steps above again.

docs/tango/daemon/usb/_category_.yml

@@ -1,6 +1,6 @@
 position: 1
-label: "Create USB connection"
+label: "USB connection"
 collapsed: false
 link:
   type: generated-index
-  title: "Create USB connection"
+  title: "USB connection"

docs/tango/daemon/usb/monitor-devices.mdx → docs/tango/daemon/usb/watch-devices.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 5
 ---
 
-# Monitor devices
+# Watch devices
 
 `@yume-chan/adb-daemon-webusb` package also provides a `AdbDaemonWebUsbDeviceWatcher` class that wraps WebUSB API to monitor device additions and removals.
 

docs/tango/index.mdx

@@ -8,64 +8,59 @@ import TabItem from "@theme/TabItem";
 
 # Quick Start
 
-Tango is a TypeScript re-implementation of [Android Debug Bridge](https://developer.android.com/studio/command-line/adb) (ADB) client. It works in both Node.js and Web browser by using different packages.
+Tango is a TypeScript re-implementation of ADB ([Android Debug Bridge](https://developer.android.com/studio/command-line/adb)) client.
+
+## Pre-requisites
+
+Tango runs on both Node.js and Web browsers. It requires the following features:
+
+* [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). `ReadableStream`, `WritableStream` and `TransformStream` must be available on `globalThis`. If not, a polyfill like [`web-streams-polyfill`](https://www.npmjs.com/package/web-streams-polyfill) can be used.
+* BigInt. This can't be polyfilled.
+* Promise
+
+Recent versions of Node.js and Web browsers should have all these features.
 
 ## Installation
 
-Tango is split into multiple packages to handle different runtimes. You need to install at least two packages to use Tango
+Tango is split into multiple packages to handle different runtimes. First, install the two core packages:
 
-1. [`@yume-chan/adb`](https://www.npmjs.com/package/@yume-chan/adb): The core package
-2. [`@yume-chan/stream-extra`](https://www.npmjs.com/package/@yume-chan/stream-extra): Polyfill for [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) and utilities for streams
-3. A transport object to communicate with devices
+1. [`@yume-chan/adb`](https://www.npmjs.com/package/@yume-chan/adb): The platform-independent ADB client implementation
+2. [`@yume-chan/stream-extra`](https://www.npmjs.com/package/@yume-chan/stream-extra): Type definitions and utilities for [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).
 
 ```sh npm2yarn
 npm i @yume-chan/adb @yume-chan/stream-extra
 ```
 
-## Direct Connection Transport
-
-In this mode, Tango holds an exclusive, direct connection to the Android device. Google ADB is not required, nor compatible with this mode.
+Depending on the runtime and connection type, additional packages are required to communicate with devices (see below).
 
-This mode is suitable for running on end-users' devices where Google ADB is not installed, or on mobile devices where Google ADB is not available.
+## Direct Connection Transport
 
-`AdbDaemonTransport` class from `@yume-chan/adb` package provides this mode. Because the API for connecting to devices varies by platform and connection type, `AdbDaemonTransport` accepts a custom connection object.
+ADB Daemon is a program running on Android devices (when Developer Options are enabled) that handles ADB commands.
 
-<Tabs className="runtime-tabs" groupId="direct-connection">
-    <TabItem value="usb" label="USB">
+In this mode, Tango connects to the ADB daemon directly. This means it can run on devices without Google ADB (not installed, or not available, for example on mobile devices).
 
-:::note[Next Step]
+Direct connection mode supports three connection methods:
 
-[Create USB connection](./daemon/usb/device-manager.md)
-
-:::
+* USB connection: requires a Web browser with WebUSB support (currently, only Chromium-based ones), or Node.js with `usb` package. Note that only one program (or Tango instance) can connect to a device at a time, so it's not compatible with Google ADB server.
+* ADB over Wi-Fi: uses TCP sockets, thus not available in Web browsers. In Node.js, it can be implemented using the built-in `net` module. Note that this refers to the old `adb tcpip` mode, not the new Wireless Debugging/`adb pair` mode added in Android 11.
 
-    </TabItem>
-    <TabItem value="tcp" label="TCP">
+* In addition, Tango also accepts custom connection implementations. For example, a WebSocket connection can forward TCP connections from a Node.js server to a Web browser.
 
 :::note[Next Step]
 
-[Create TCP connection](./daemon/tcp/enable.mdx)
+[Create Direct Connection](./daemon/index.mdx)
 
 :::
 
-    </TabItem>
-
-<TabItem value="custom" label="Custom">
-
-:::note[Next Step]
-
-[Create custom connection](./daemon/custom-connection.mdx)
-
-:::
+## Google ADB Client Transport
 
-</TabItem>
-</Tabs>
+Google ADB server is a program running on PC that manages devices and allows sharing a device with multiple clients.
 
-## Google ADB Client Transport
+In this mode, Tango talks to a Google ADB server, which can either run on the same machine or on a remote machine.
 
-In this mode, Tango talks to a Google ADB server, which can either run on the same machine or on a remote machine. Google ADB server manages the connection to devices, so multiple clients (including Tango) can share the same device.
+Google ADB server is traditionally the only way to connect to the ADB daemon running on Android devices, so this mode is compatible with other programs that use ADB, such as Android Studio.
 
-`AdbServerClient` class from `@yume-chan/adb` package provides this mode. Similar to `AdbDaemonTransport`, `AdbServerClient` accepts a custom connector for connecting to the server on different environments.
+Because Google ADB server listens on a TCP socket, this mode is only available in Node.js. In Web browsers, a custom connector is required to forward TCP sockets from backend server.
 
 :::note[Next Step]
 
@@ -75,7 +70,9 @@ In this mode, Tango talks to a Google ADB server, which can either run on the sa
 
 ## Custom Transport
 
-Tango also supports custom transports. For example, a mock transport can be used in tests, or a WebSocket transport to access devices on a server over the Internet.
+ADB protocol is a stream multiplexing protocol, where each ADB command is a logical stream, called ADB socket. The goal of both the Direct Connection Transport and Google ADB Client Transport is to manage ADB sockets.
+
+Tango also supports custom transports that works directly on ADB socket level. For example, a mock transport can be used in tests, or a WebSocket transport to access devices on a server over the Internet.
 
 :::note[Next Step]
 

docusaurus.config.js

@@ -185,6 +185,7 @@ export default {
   tagline: "Documentation for Tango ADB library",
   url: "https://docs.tangoapp.dev",
   baseUrl: "/",
+  trailingSlash: true,
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
   favicon: "img/logo.svg",

package.json

@@ -14,19 +14,19 @@
         "write-heading-ids": "docusaurus write-heading-ids"
     },
     "dependencies": {
-        "@docusaurus/core": "^3.1.0",
-        "@docusaurus/preset-classic": "^3.1.0",
-        "@docusaurus/remark-plugin-npm2yarn": "^3.1.0",
-        "@docusaurus/theme-mermaid": "^3.1.0",
+        "@docusaurus/core": "^3.2.1",
+        "@docusaurus/preset-classic": "^3.2.1",
+        "@docusaurus/remark-plugin-npm2yarn": "^3.2.1",
+        "@docusaurus/theme-mermaid": "^3.2.1",
         "@easyops-cn/docusaurus-search-local": "^0.40.1",
-        "@mdx-js/react": "^3.0.0",
+        "@mdx-js/react": "^3.0.1",
         "@svgr/webpack": "^8.1.0",
         "clsx": "^2.1.0",
         "file-loader": "^6.2.0",
-        "prettier": "^3.2.4",
+        "prettier": "^3.2.5",
         "react": "^18.2.0",
         "react-dom": "^18.2.0",
-        "typescript": "^5.3.3",
+        "typescript": "^5.4.4",
         "url-loader": "^4.1.1"
     },
     "browserslist": {
@@ -42,12 +42,12 @@
         ]
     },
     "devDependencies": {
-        "@docusaurus/module-type-aliases": "^3.1.0",
-        "@docusaurus/theme-classic": "^3.1.0",
-        "@docusaurus/tsconfig": "^3.1.0",
-        "@docusaurus/types": "^3.1.0",
+        "@docusaurus/module-type-aliases": "^3.2.1",
+        "@docusaurus/theme-classic": "^3.2.1",
+        "@docusaurus/tsconfig": "^3.2.1",
+        "@docusaurus/types": "^3.2.1",
         "@types/mdast": "^4.0.3",
-        "@types/node": "^20.11.6",
+        "@types/node": "^20.12.5",
         "prism-react-renderer": "^2.3.1",
         "unist-util-visit": "^5.0.0"
     }