docs: fix docstring by typescript_docstring.mdc

linzhengyu · linzhengyu · commit fa5c05aa06f1 · 2025-12-19T15:23:43.000+08:00
diff --git a/app/components/layout/ChatModeMenu.tsx b/app/components/layout/ChatModeMenu.tsx
@@ -31,6 +31,7 @@ interface ChatModeMenuProps {
  *
  * @param chatMode Current chat mode.
  * @param onModeSelect Callback function called when a mode is selected.
+ * @param enableLiveChat Whether live chat mode is enabled. Defaults to true.
  * @returns JSX.Element The chat mode menu UI component.
  */
 export default function ChatModeMenu({
@@ -42,8 +43,16 @@ export default function ChatModeMenu({
   const [showChatModeMenu, setShowChatModeMenu] = useState(false)
   const chatModeMenuRef = useRef<HTMLDivElement>(null)
 
-  // Close chat mode menu when clicking outside
+  /**
+   * Close chat mode menu when clicking outside.
+   */
   useEffect(() => {
+    /**
+     * Handle click outside event to close the menu.
+     * 
+     * @param event The mouse event.
+     * @returns void
+     */
     function handleClickOutside(event: MouseEvent) {
       if (
         chatModeMenuRef.current &&
@@ -61,6 +70,8 @@ export default function ChatModeMenu({
 
   /**
    * Get the display text for the current chat mode.
+   * 
+   * @returns The translated text for the current chat mode.
    */
   const getChatModeText = () => {
     switch (chatMode) {
@@ -77,6 +88,11 @@ export default function ChatModeMenu({
 
   /**
    * Handle chat mode selection.
+   * 
+   * Calls the onModeSelect callback and closes the menu.
+   * 
+   * @param mode The selected chat mode.
+   * @returns void
    */
   const handleChatModeSelect = (mode: 'text' | 'voice' | 'live') => {
     onModeSelect(mode)
diff --git a/app/components/layout/Chatbox.tsx b/app/components/layout/Chatbox.tsx
@@ -3,7 +3,6 @@
 import React, { useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { GlobalState } from '@/library/babylonjs/core'
-import { States } from '@/library/babylonjs/runtime/fsm/states'
 import {
   Conditions,
   ConditionedMessage,
@@ -25,6 +24,7 @@ interface ChatboxProps {
  * A text input component for sending chat messages.
  * Displays a textarea and send button, positioned at the bottom center of the screen.
  *
+ * @param globalState Global state for accessing BabylonJS scene and runtime.
  * @returns JSX.Element The chatbox UI component.
  */
 export default function Chatbox({ globalState }: ChatboxProps) {
@@ -33,6 +33,11 @@ export default function Chatbox({ globalState }: ChatboxProps) {
 
   /**
    * Handle sending chat message.
+   * 
+   * Sends the current chat message to the state machine. If an animation is currently playing,
+   * it will interrupt the animation before sending the message.
+   * 
+   * @returns void
    */
   const handleSendMessage = () => {
     if (chatMessage.trim()) {
@@ -51,6 +56,12 @@ export default function Chatbox({ globalState }: ChatboxProps) {
 
   /**
    * Handle Enter key press in textarea.
+   * 
+   * Sends the message when Enter is pressed without Shift. Prevents default behavior
+   * to avoid adding a new line.
+   * 
+   * @param e The keyboard event from the textarea.
+   * @returns void
    */
   const handleTextareaKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
     if (e.key === 'Enter' && !e.shiftKey) {
diff --git a/app/components/layout/LiveStreamInput.tsx b/app/components/layout/LiveStreamInput.tsx
@@ -33,6 +33,7 @@ interface LiveStreamInputProps {
  * A component for inputting and confirming live stream URLs.
  * Displays an input field and confirm button positioned next to the chat mode button.
  *
+ * @param globalState Global state for accessing BabylonJS scene and runtime.
  * @returns JSX.Element The live stream input UI component.
  */
 export default function LiveStreamInput({ globalState }: LiveStreamInputProps) {
@@ -44,93 +45,107 @@ export default function LiveStreamInput({ globalState }: LiveStreamInputProps) {
   const clientRef = useRef<DanmakuWebSocketClient | null>(null)
 
   /**
-   * 解析直播流 URL，提取服务器地址和房间标识
-   * 支持两种格式：
+   * Parse live stream URL and extract server address and room identifier.
+   * 
+   * Supports two formats:
    * 1. file:// URL: file:///path/loader.html?url=http%3A%2F%2Flocalhost%3A12450%2Froom%2FKEY%3FroomKeyType%3D2
-   * 2. 直接 HTTP URL: http://localhost:12450/room/KEY?roomKeyType=2
+   * 2. Direct HTTP URL: http://localhost:12450/room/KEY?roomKeyType=2
+   * 
+   * @param url The live stream URL to parse.
+   * @returns An object containing serverUrl and roomKey, or null if parsing fails.
    */
   const parseLiveStreamUrl = (url: string): { serverUrl: string; roomKey: RoomKey } | null => {
     try {
       let actualUrl = url
       
-      // 处理 file:// 协议的 URL
+      // Handle file:// protocol URLs
       if (url.startsWith('file://')) {
         const urlObj = new URL(url)
-        // 获取 url 查询参数
+        // Get url query parameter
         const urlParam = urlObj.searchParams.get('url')
         if (!urlParam) {
-          console.error('file:// URL 中缺少 url 参数')
+          console.error('Missing url parameter in file:// URL')
           return null
         }
-        // URL 解码
+        // URL decode
         actualUrl = decodeURIComponent(urlParam)
       }
 
-      // 解析实际的 URL
+      // Parse the actual URL
       const urlObj = new URL(actualUrl)
       const serverUrl = `${urlObj.protocol}//${urlObj.host}`
       
-      // 从路径中提取 roomKey（例如：/room/F3RY9LX2M9KW9）
+      // Extract roomKey from path (e.g., /room/F3RY9LX2M9KW9)
       const pathParts = urlObj.pathname.split('/').filter(Boolean)
       if (pathParts.length < 2 || pathParts[0] !== 'room') {
-        console.error('URL 路径格式不正确，期望格式: /room/KEY')
+        console.error('Invalid URL path format, expected format: /room/KEY')
         return null
       }
       
-      const roomValue = pathParts[1] // 获取 roomKey
+      const roomValue = pathParts[1] // Get roomKey
       
-      // 从查询参数中获取 roomKeyType，默认为 2（身份码）
+      // Get roomKeyType from query parameter, default to 2 (identity code)
       const roomKeyTypeParam = urlObj.searchParams.get('roomKeyType')
-      let roomKeyType: 1 | 2 = 2 // 默认为身份码
+      let roomKeyType: 1 | 2 = 2 // Default to identity code
       
       if (roomKeyTypeParam) {
         const type = parseInt(roomKeyTypeParam, 10)
         if (type === 1 || type === 2) {
           roomKeyType = type as 1 | 2
         }
       } else {
-        // 如果没有指定 roomKeyType，尝试根据 roomValue 判断
+        // If roomKeyType is not specified, try to determine from roomValue
         const roomId = parseInt(roomValue, 10)
         if (!isNaN(roomId)) {
-          roomKeyType = 1 // 数字则认为是房间ID
+          roomKeyType = 1 // Numeric value is considered room ID
         }
       }
       
-      // 构建 roomKey
+      // Build roomKey
       const roomKey: RoomKey = {
         type: roomKeyType,
         value: roomKeyType === 1 ? parseInt(roomValue, 10) : roomValue,
       }
 
       return { serverUrl, roomKey }
     } catch (error) {
-      console.error('解析 URL 失败:', error)
+      console.error('Failed to parse URL:', error)
       return null
     }
   }
 
+  /**
+   * Send user text message to the state machine.
+   * 
+   * Processes messages from queues (super chat, gift, text) and sends them to the state machine
+   * when it's in IDLE state. In auto mode, sends a "no message" notification if no messages
+   * have been received for more than 10 seconds.
+   * 
+   * @param lastTextMessageTime The timestamp of the last text message, or null if none.
+   * @returns void
+   */
   const sendUserTextMessage = (lastTextMessageTime: number | null) => {
     if (globalState?.stateMachine?.stateValue === States.IDLE) {
       if (clientRef.current) {
         if (clientRef.current.superChatQueue.size > 0) {
           const message = clientRef.current.superChatQueue.dequeue()
           if (message) {
-            const formattedMessages = `[${message.authorName}]发送了醒目留言: ${message.content}`
+            const formattedMessages = `[${message.authorName}] sent super chat: ${message.content}`
             globalState?.stateMachine?.putConditionedMessage(
               new ConditionedMessage(Conditions.USER_TEXT_INPUT, { message: formattedMessages }),
             )
-            console.log('[发送后台消息]: ', formattedMessages)
+            console.log('[Send background message]: ', formattedMessages)
             return
           }
         }
         if (clientRef.current.giftQueue.size > 0) {
           const message = clientRef.current.giftQueue.dequeue()
           if (message) {
-            const formattedMessages = `[${message.authorName}]发送了礼物: ${message.giftName}, ${message.num} 件`
+            const formattedMessages = `[${message.authorName}] sent gift: ${message.giftName}, ${message.num} pieces`
             globalState?.stateMachine?.putConditionedMessage(
               new ConditionedMessage(Conditions.USER_TEXT_INPUT, { message: formattedMessages }),
             )
-            console.log('[发送后台消息]: ', formattedMessages)
+            console.log('[Send background message]: ', formattedMessages)
             return
           }
         }
@@ -142,111 +157,120 @@ export default function LiveStreamInput({ globalState }: LiveStreamInputProps) {
           globalState?.stateMachine?.putConditionedMessage(
             new ConditionedMessage(Conditions.USER_TEXT_INPUT, { message: formattedMessages }),
           )
-          console.log('[发送后台消息]: ', formattedMessages)
+          console.log('[Send background message]: ', formattedMessages)
           return
         }else{
           if (autoMode && lastTextMessageTime !== null && Date.now() - lastTextMessageTime > 10000) {
             globalState?.stateMachine?.putConditionedMessage(
-              new ConditionedMessage(Conditions.USER_TEXT_INPUT, { message: '无消息/No message' }),
+              new ConditionedMessage(Conditions.USER_TEXT_INPUT, { message: 'No message' }),
             )
-            console.log('[发送后台消息]: 无消息/No message')
+            console.log('[Send background message]: No message')
           }
           return
         }
       }
     }
   }
   /**
-   * 消息处理器
+   * Message handler for danmaku WebSocket client.
    */
   const messageHandler: DanmakuMessageHandler = {
     onDebugMsg: (msg: string) => {
-      console.log('[弹幕客户端]', msg)
+      console.log('[Danmaku client]', msg)
       setConnectionStatus(msg)
     },
     onHeartBeat: (lastTextMessageTime: number | null) => {
       sendUserTextMessage(lastTextMessageTime)
     },
     onAddText: (message: TextMessage) => {
-      console.log('[弹幕]', message.authorName, ':', message.content)
+      console.log('[Danmaku]', message.authorName, ':', message.content)
       if (clientRef.current) {
         clientRef.current.messageQueue.enqueue(message)
         sendUserTextMessage(Date.now())
       }
     },
     onAddGift: (message: GiftMessage) => {
-      console.log('[礼物]', message.authorName, ':', message.giftName, 'x', message.num)
+      console.log('[Gift]', message.authorName, ':', message.giftName, 'x', message.num)
       if (clientRef.current) {
         clientRef.current.giftQueue.enqueue(message)
         sendUserTextMessage(Date.now())
       }
     },
     onAddMember: (message: MemberMessage) => {
-      console.log('[成员]', message.authorName, '加入了直播间')
-      // 这里可以添加处理成员消息的逻辑
+      console.log('[Member]', message.authorName, 'joined the live stream')
+      // Logic for handling member messages can be added here
     },
     onAddSuperChat: (message: SuperChatMessage) => {
-      console.log('[超级聊天]', message.authorName, ':', message.content, '¥', message.price)
+      console.log('[Super chat]', message.authorName, ':', message.content, '¥', message.price)
       if (clientRef.current) {
         clientRef.current.superChatQueue.enqueue(message)
         sendUserTextMessage(Date.now())
       }
     },
     onFatalError: (error: string) => {
-      console.error('[致命错误]', error)
-      setConnectionStatus(`连接失败: ${error}`)
+      console.error('[Fatal error]', error)
+      setConnectionStatus(`Connection failed: ${error}`)
       setIsConnected(false)
     },
   }
 
   /**
    * Handle live stream URL confirmation.
+   * 
+   * Parses the URL, disconnects any existing connection, and creates a new WebSocket client
+   * to connect to the live stream server.
+   * 
+   * @returns void
    */
   const handleConfirm = () => {
     if (!liveStreamUrl.trim()) {
       return
     }
 
-    // 如果已经连接，先断开旧连接
+    // If already connected, disconnect the old connection first
     if (clientRef.current) {
       clientRef.current.stop()
       clientRef.current = null
     }
 
-    // 解析 URL
-    // URL 格式示例: 
+    // Parse URL
+    // URL format examples:
     // - file:///path/loader.html?url=http%3A%2F%2Flocalhost%3A12450%2Froom%2FKEY%3FroomKeyType%3D2
     // - http://localhost:12450/room/KEY?roomKeyType=2
     const parsed = parseLiveStreamUrl(liveStreamUrl.trim())
     if (!parsed) {
-      alert('无效的直播流 URL，请检查格式\n支持格式:\n1. file:// URL (带 url 参数)\n2. http://server:port/room/KEY?roomKeyType=2')
+      alert('Invalid live stream URL, please check the format\nSupported formats:\n1. file:// URL (with url parameter)\n2. http://server:port/room/KEY?roomKeyType=2')
       return
     }
 
-    // 创建 WebSocket 客户端
+    // Create WebSocket client
     const client = new DanmakuWebSocketClient(parsed.serverUrl, parsed.roomKey, false)
     client.setMsgHandler(messageHandler)
     client.start()
 
     clientRef.current = client
     setIsConnected(true)
-    setConnectionStatus('连接中...')
+    setConnectionStatus('Connecting...')
   }
 
   /**
-   * 断开连接
+   * Handle disconnection from the live stream.
+   * 
+   * Stops the WebSocket client and updates the connection status.
+   * 
+   * @returns void
    */
   const handleDisconnect = () => {
     if (clientRef.current) {
       clientRef.current.stop()
       clientRef.current = null
       setIsConnected(false)
-      setConnectionStatus('已断开')
+      setConnectionStatus('Disconnected')
     }
   }
 
   /**
-   * 组件卸载时清理连接
+   * Clean up connection when component unmounts.
    */
   useEffect(() => {
     return () => {
@@ -259,6 +283,11 @@ export default function LiveStreamInput({ globalState }: LiveStreamInputProps) {
 
   /**
    * Handle Enter key press in input.
+   * 
+   * Triggers the confirm action when Enter is pressed.
+   * 
+   * @param e The keyboard event from the input element.
+   * @returns void
    */
   const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
     if (e.key === 'Enter') {
diff --git a/app/contexts/BabylonJSContext.tsx b/app/contexts/BabylonJSContext.tsx
@@ -293,7 +293,7 @@ function BabylonJSProvider({
   return (
     <BabylonJSContext.Provider value={{ canvas, globalState }}>
       {children}
-      <ChatModeMenu chatMode={chatMode} onModeSelect={handleChatModeSelect} enableLiveChat={true} />
+      <ChatModeMenu chatMode={chatMode} onModeSelect={handleChatModeSelect} enableLiveChat={false} />
 
       {chatMode === 'text' && (
         <Chatbox globalState={globalState} />
diff --git a/app/utils/danmakuWebSocketClient.ts b/app/utils/danmakuWebSocketClient.ts
