docs: add error handling guide

.vscode/settings.json

@@ -3,7 +3,7 @@
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.codeActionsOnSave": {
-    "source.fixAll": true
+    "source.fixAll": "explicit"
   },
   "svelte.enable-ts-plugin": true,
   "cSpell.ignorePaths": [

README-zh.md

@@ -354,6 +354,47 @@ return (
 
 请参考文档：[如何为 fastboard 实现 UI](./docs/zh/ui.md)
 
+<h2 id="#error-handling">异常处理</h2>
+
+你会因为以下情况收到异常回调：
+
+- 因为断网等无法连上白板服务器
+- 因为网络不稳自动进入重连状态
+- 房间被封禁
+
+注意，白板内部自带重试逻辑，用户无需手写，如果白板真的断开连接，你必须直接退出房间。
+
+请参考以下代码适当地处理这些异常情况：
+
+```js
+try {
+  fastboard = await createFastboard({
+    sdkConfig: {
+      onWhiteSetupFailed(error) {
+        console.error("Failed to find the whiteboard server", error);
+      },
+    },
+    joinRoom: {
+      callbacks: {
+        onPhaseChanged(phase) {
+          if (phase === "reconnecting") console.log("Whiteboard connection lost, reconnecting...");
+        },
+        onDisconnectWithError(error) {
+          console.error("Failed to connect to whiteboard server", error);
+        },
+        onKickedWithReason(reason) {
+          console.log("You're kicked by", reason);
+          // 正常退出房间
+          leaveRoom();
+        },
+      },
+    },
+  });
+} catch (error) {
+  console.error("Failed to join whiteboard room", error);
+}
+```
+
 ## License
 
 MIT @ [netless](https://github.com/netless-io)

README.md

@@ -346,6 +346,47 @@ return (
 
 Then refer to the doc: [Write Your Own UI (for Fastboard)](./docs/en/ui.md).
 
+## Error Handling
+
+You will get callbacks when:
+
+- Cannot connect to server at the very beginning
+- Connecting status changed (to `reconnecting` or `disconnected`)
+- Kicked from room (when the room is banned from the backend)
+
+Note that Fastboard will reconnect automatically internally, you only have to do things below to ensure the user experience.
+
+To properly handle these cases, please refer to this piece of code:
+
+```js
+try {
+  fastboard = await createFastboard({
+    sdkConfig: {
+      onWhiteSetupFailed(error) {
+        console.error("Failed to find the whiteboard server", error);
+      },
+    },
+    joinRoom: {
+      callbacks: {
+        onPhaseChanged(phase) {
+          if (phase === "reconnecting") console.log("Whiteboard connection lost, reconnecting...");
+        },
+        onDisconnectWithError(error) {
+          console.error("Failed to connect to whiteboard server");
+        },
+        onKickedWithReason(reason) {
+          console.log("You're kicked by", reason);
+          // Properly close this room
+          leaveRoom();
+        },
+      },
+    },
+  });
+} catch (error) {
+  console.error("Failed to join whiteboard room", error);
+}
+```
+
 ## License
 
 MIT @ [netless](https://github.com/netless-io)