docs(chat): consolidate multi-role protocol

src/stores/chat/chat-context.tsx

@@ -8,12 +8,7 @@ import { chatMachine } from "./chat-machine";
 import type { ChatEvent, ChatState as MachineContext } from "./chat-machine";
 import { appendPromotionMessage } from "./helper/promotion";
 
-/**
- * 对外暴露的 State 形状
- *
- * isGuest 字段已删 —— 由 chat-screen 派生自 `auth.loginStatus === "guest"`。
- *   消费方（chat-screen）通过 `useAuthState()` 取 loginStatus，本地派生 isGuest。
- */
+/** Chat UI reads this projection instead of the machine snapshot directly. */
 interface ChatState {
   characterId: string;
   characterErrorCode: MachineContext["characterErrorCode"];
@@ -25,7 +20,7 @@ interface ChatState {
   canSendMessage: boolean;
   upgradePromptVisible: boolean;
   upgradeReason: MachineContext["upgradeReason"];
-  /** history 初始加载完成标志（local → network → save 跑完） —— UI 可用此显示 loading */
+  /** True as soon as a local snapshot or the first network result is renderable. */
   historyLoaded: boolean;
   hasMoreHistory: boolean;
   isLoadingMoreHistory: boolean;

src/stores/chat/chat-events.ts

@@ -1,26 +1,14 @@
 /**
- * Chat 状态机：事件联合
- *
- * 事件名与原 Dart ChatEvent 对齐。
- *
- * 历史：原本有 `ChatAuthStatusChanged`（chat 机器刷新 isGuest）—— 已删。
- * 鉴权状态变化（loginStatus）由 <ChatAuthSync /> 通过 `useAuthState()` 订阅，
- * chat 机器不感知鉴权。
- *
- * 鉴权生命周期事件（本轮新增）：
- *   - `ChatGuestLogin`：游客进入 /chat —— 拉服务器端首屏
- *   - `ChatUserLogin`：其他登录用户进入 /chat —— 拉服务器端首屏
- *   - `ChatLogout`：正式登录用户登出 —— 清消息
- *
- * 设计：所有历史 / 配额相关副作用全部通过派发事件给 chat 机器处理，
- * chat-screen 不直接读 AuthStorage（除 token 取值）。
+ * Public events for one character-scoped Chat actor.
+ * Authentication synchronization dispatches the lifecycle events; history,
+ * quota, send, and unlock side effects remain owned by the machine.
  */
 import type { PendingChatUnlockKind } from "@/lib/navigation/chat_unlock_session";
 import type { ChatLockType } from "@/data/schemas/chat";
 import type { PendingChatPromotion } from "@/data/storage/navigation";
 
 export type ChatEvent =
-  // 鉴权生命周期（登录态变化后由 ChatAuthSync 派）
+  // Authentication lifecycle dispatched by ChatAuthSync.
   | { type: "ChatGuestLogin" }
   | { type: "ChatUserLogin"; token: string }
   | { type: "ChatLogout" }
@@ -40,7 +28,7 @@ export type ChatEvent =
     }
   | { type: "ChatOlderHistoryLoadFailed"; error: unknown }
   | { type: "ChatHistoryRefreshRequested" }
-  // 业务事件
+  // Chat domain events.
   | { type: "ChatSendMessage"; content: string }
   | { type: "ChatSendImage"; imageBase64: string }
   | {

src/stores/chat/helper/history.ts

@@ -2,7 +2,7 @@ import type { UiMessage } from "@/stores/chat/ui-message";
 
 import type { ChatState } from "../chat-state";
 
-// The initial history request remains bounded even though pagination is disabled.
+// Initial and subsequent history pages use the same bounded page size.
 export const CHAT_HISTORY_LIMIT = 50;
 
 export function applyHistoryLoadedOutput(