refactor(characters): drive shared UI from active character

docs/backend/FRONTEND_MULTI_CHARACTER_API.md

@@ -6,7 +6,7 @@
 
 迁移目标：
 
-1. 前端维护统一的本地角色目录，后端只识别稳定角色 ID。
+1. 前端通过统一的 Character Catalog 边界读取角色目录，当前由本地只读目录提供，后端只识别稳定角色 ID。
 2. 同一用户可以分别与多个角色聊天。
 3. 不同角色的聊天历史、媒体、锁内容、私密相册和打赏归属必须隔离。
 4. 钱包、VIP、支付套餐和每日免费额度继续按用户全局共享。
@@ -29,9 +29,9 @@
 | pro 预发环境 | `https://proapi.banlv-ai.com` |
 | production 生产环境 | `https://api.banlv-ai.com` |
 
-## 2. 前端本地角色目录
+## 2. 前端 Character Catalog
 
-角色列表不通过网络接口加载。前端在本地维护只读目录，并使用 `slug` 解析角色路径、使用 `id` 调用后端业务接口。
+后端角色目录协议尚未确定。过渡阶段由前端本地只读 Catalog 提供角色，并使用 `slug` 解析角色路径、使用 `id` 调用后端业务接口。业务页面只消费 Catalog 边界；后续切换为服务端目录时不改变角色路由和业务组件接口。
 
 当前角色：
 
@@ -41,7 +41,7 @@
 | `character_maya` | `maya` | Maya Tan | `/images/avatar/maya.png` | `/images/cover/maya.png` | `/images/private-room/banner/maya.png` |
 | `character_nayeli` | `nayeli` | Nayeli Cervantes | `/images/avatar/nayeli.png` | `/images/cover/nayeli.png` | `/images/private-room/banner/nayeli.png` |
 
-本地记录同时保存短名称及 Splash、Private Room、Tip 使用的角色文案。后端不提供头像、封面、展示名称或角色目录接口，但后端配置中的角色 ID 必须与前端目录一致。
+当前开发环境开放表中的全部角色。Catalog 同时保存短名称、页面资源、空聊天问候语、排序及 Chat、Private Room、Tip 能力。后端配置中的角色 ID 必须与前端目录一致。
 
 ## 3. 聊天接口调整
 

package.json

@@ -70,6 +70,7 @@
     "barrelsby": "^2.8.1",
     "eslint": "^9",
     "eslint-config-next": "16.2.7",
+    "fake-indexeddb": "^6.2.5",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4",
     "typescript": "^5",

pnpm-lock.yaml

@@ -105,6 +105,9 @@ importers:
       eslint-config-next:
         specifier: 16.2.7
         version: 16.2.7(@typescript-eslint/parser@8.60.1(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)
+      fake-indexeddb:
+        specifier: ^6.2.5
+        version: 6.2.5
       jsdom:
         specifier: ^29.1.1
         version: 29.1.1
@@ -2339,6 +2342,10 @@ packages:
     resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==}
     engines: {node: '>=12.0.0'}
 
+  fake-indexeddb@6.2.5:
+    resolution: {integrity: sha512-CGnyrvbhPlWYMngksqrSSUT1BAVP49dZocrHuK0SvtR0D5TMs5wP0o3j7jexDJW01KSadjBp1M/71o/KR3nD1w==}
+    engines: {node: '>=18'}
+
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -6193,6 +6200,8 @@ snapshots:
 
   expect-type@1.3.0: {}
 
+  fake-indexeddb@6.2.5: {}
+
   fast-deep-equal@3.1.3: {}
 
   fast-glob@3.3.1:

src/app/_components/__tests__/tailwind-components.test.tsx

@@ -48,7 +48,13 @@ describe("shared Tailwind components", () => {
 
   it("renders CharacterAvatar with dynamic sizing and image utilities", () => {
     const html = renderToStaticMarkup(
-      <CharacterAvatar size={48} imageSize={96} className="custom-avatar" />,
+      <CharacterAvatar
+        src="/images/avatar/maya.png"
+        alt="Maya Tan"
+        size={48}
+        imageSize={96}
+        className="custom-avatar"
+      />,
     );
 
     expect(html).toContain("inline-flex");
@@ -56,7 +62,7 @@ describe("shared Tailwind components", () => {
     expect(html).toContain("width:48px");
     expect(html).toContain("height:48px");
     expect(html).toContain("size-full object-cover");
-    expect(html).toContain("%2Fimages%2Favatar%2Felio.png");
+    expect(html).toContain("%2Fimages%2Favatar%2Fmaya.png");
   });
 
   it("renders UserMessageAvatar custom and fallback images", () => {

src/app/_components/character-avatar.tsx

@@ -4,8 +4,8 @@ import Image from "next/image";
 import type { CSSProperties } from "react";
 
 export interface CharacterAvatarProps {
-  src?: string;
+  src: string;
-  alt?: string;
+  alt: string;
   className?: string;
   size?: number | string;
   imageSize?: number;
@@ -13,8 +13,8 @@ export interface CharacterAvatarProps {
 }
 
 export function CharacterAvatar({
-  src = "/images/avatar/elio.png",
+  src,
-  alt = "Elio Silvestri",
+  alt,
   className,
   size = 43,
   imageSize,

src/app/_components/core/__tests__/tailwind-components.test.tsx

@@ -79,6 +79,7 @@ describe("core Tailwind components", () => {
       <AppBottomNav
         activeItem="chat"
         variant="dark"
+        privateRoomLabel="Maya Private room"
         onChatClick={() => undefined}
         onPrivateRoomClick={() => undefined}
       />,
@@ -87,6 +88,7 @@ describe("core Tailwind components", () => {
       <AppBottomNav
         activeItem="privateRoom"
         variant="warm"
+        privateRoomLabel="Maya Private room"
         onChatClick={() => undefined}
         onPrivateRoomClick={() => undefined}
       />,
@@ -99,7 +101,7 @@ describe("core Tailwind components", () => {
     );
     expect(privateRoomHtml).toMatch(/class="[^"]*warm[^"]*"/);
     expect(privateRoomHtml).toMatch(
-      /<button[^>]*aria-current="page"[^>]*>.*?<span>Elio Private room<\/span>/,
+      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private room<\/span>/,
     );
     expect(chatHtml).toContain('data-analytics-key="navigation.chat"');
     expect(privateRoomHtml).toContain(

src/app/_components/core/app-bottom-nav.tsx

@@ -10,7 +10,7 @@ export type AppBottomNavVariant = "warm" | "dark";
 export interface AppBottomNavProps {
   activeItem?: AppBottomNavItem | null;
   variant?: AppBottomNavVariant;
-  privateRoomLabel?: string;
+  privateRoomLabel: string;
   onChatClick: () => void;
   onPrivateRoomClick: () => void;
 }
@@ -18,7 +18,7 @@ export interface AppBottomNavProps {
 export function AppBottomNav({
   activeItem = null,
   variant = "warm",
-  privateRoomLabel = "Elio Private room",
+  privateRoomLabel,
   onChatClick,
   onPrivateRoomClick,
 }: AppBottomNavProps) {

src/app/characters/[characterSlug]/chat/layout.tsx

@@ -13,10 +13,13 @@ export default async function CharacterChatLayout({
 }) {
   const { characterSlug } = await params;
   const character = getCharacterBySlug(characterSlug);
-  if (!character) notFound();
+  if (!character?.capabilities.chat) notFound();
 
   return (
-    <ChatRouteProviders characterId={character.id}>
+    <ChatRouteProviders
+      characterId={character.id}
+      emptyChatGreeting={character.emptyChatGreeting}
+    >
       {children}
     </ChatRouteProviders>
   );

src/app/characters/[characterSlug]/private-room/layout.tsx

@@ -13,7 +13,7 @@ export default async function CharacterPrivateRoomLayout({
 }) {
   const { characterSlug } = await params;
   const character = getCharacterBySlug(characterSlug);
-  if (!character) notFound();
+  if (!character?.capabilities.privateRoom) notFound();
 
   return (
     <PrivateRoomRouteProvider characterId={character.id}>

src/app/characters/[characterSlug]/tip/layout.tsx

@@ -1,11 +1,23 @@
 import type { ReactNode } from "react";
+import { notFound } from "next/navigation";
 
+import { getCharacterBySlug } from "@/data/constants/character";
 import { PaymentRouteProvider } from "@/providers/payment-route-provider";
 
-export default function CharacterTipLayout({
+export default async function CharacterTipLayout({
   children,
+  params,
 }: {
   children: ReactNode;
+  params: Promise<{ characterSlug: string }>;
 }) {
-  return <PaymentRouteProvider>{children}</PaymentRouteProvider>;
+  const { characterSlug } = await params;
+  const character = getCharacterBySlug(characterSlug);
+  if (!character?.capabilities.tip) notFound();
+
+  return (
+    <PaymentRouteProvider scopeKey={character.id}>
+      {children}
+    </PaymentRouteProvider>
+  );
 }

src/app/chat/__tests__/chat-unlock-coordinator.test.ts

@@ -20,6 +20,7 @@ const defaultScope = {
 };
 
 const promotionSession: PendingChatPromotion = {
+  characterId: "character_elio",
   promotionType: "image",
   lockType: "image_paywall",
   clientLockId: "promotion-1",
@@ -181,6 +182,7 @@ function createPendingUnlock(
 ): PendingChatUnlock {
   return {
     reason: "single_message_unlock",
+    characterId: "character_elio",
     ...input,
     stage: "auth",
     createdAt: 1,

src/app/chat/chat-screen.tsx

@@ -9,7 +9,10 @@ import {
   useChatDispatch,
   useChatState,
 } from "@/stores/chat/chat-context";
-import { useActiveCharacterRoutes } from "@/providers/character-provider";
+import {
+  useActiveCharacter,
+  useActiveCharacterRoutes,
+} from "@/providers/character-provider";
 
 import { MobileShell } from "@/app/_components/core";
 
@@ -46,6 +49,7 @@ const chatShellStyle = {
 
 export function ChatScreen() {
   const router = useRouter();
+  const character = useActiveCharacter();
   const characterRoutes = useActiveCharacterRoutes();
   const searchParams = useSearchParams();
   const state = useChatState();
@@ -58,7 +62,9 @@ export function ChatScreen() {
     loginStatus: authState.loginStatus,
     messages: state.historyMessages,
   });
-  const isPromotionBootstrapReady = useChatPromotionBootstrap();
+  const isPromotionBootstrapReady = useChatPromotionBootstrap(
+    state.characterId,
+  );
   const visibleMessages = isPromotionBootstrapReady
     ? state.messages
     : state.historyMessages;
@@ -165,7 +171,7 @@ export function ChatScreen() {
       >
         <div className="pointer-events-none absolute inset-0 z-0">
           <Image
-            src="/images/chat/bg-chatpage.png"
+            src={character.assets.chatBackground}
             alt=""
             fill
             priority

src/app/chat/components/__tests__/chat-area-scroll.test.tsx

@@ -235,6 +235,7 @@ function renderChatArea(
   act(() => {
     root.render(
       <ChatArea
+        characterId="character_elio"
         messages={messages}
         isReplyingAI={false}
         initialScrollReady={initialScrollReady}

src/app/chat/components/__tests__/locked-image-message-card.test.tsx

@@ -1,15 +1,22 @@
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
 
+import { getCharacterBySlug } from "@/data/constants/character";
+import { CharacterProvider } from "@/providers/character-provider";
+
 import { LockedImageMessageCard } from "../locked-image-message-card";
 
 describe("LockedImageMessageCard", () => {
   it("renders the promotion hint and an enabled unlock action", () => {
+    const character = getCharacterBySlug("maya");
+    if (!character) throw new Error("Missing Maya character fixture");
     const html = renderToStaticMarkup(
-      <LockedImageMessageCard
+      <CharacterProvider character={character}>
-        hint="Unlock this private photo."
+        <LockedImageMessageCard
-        onUnlock={() => undefined}
+          hint="Unlock this private photo."
-      />,
+          onUnlock={() => undefined}
+        />
+      </CharacterProvider>,
     );
 
     expect(html).toContain('aria-label="Locked private image"');

src/app/chat/components/__tests__/tailwind-components.test.tsx

@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it, vi } from "vitest";
 
@@ -25,8 +26,8 @@ vi.mock("@/router/use-app-navigator", () => ({
 
 describe("chat Tailwind components", () => {
   it("renders MessageAvatar AI and user branches with image utilities", () => {
-    const aiHtml = renderToStaticMarkup(<MessageAvatar isFromAI={true} />);
+    const aiHtml = renderWithCharacter(<MessageAvatar isFromAI={true} />);
-    const userHtml = renderToStaticMarkup(
+    const userHtml = renderWithCharacter(
       <MessageAvatar isFromAI={false} userAvatarUrl="/user-avatar.png" />,
     );
 
@@ -71,8 +72,8 @@ describe("chat Tailwind components", () => {
   });
 
   it("renders PrivateMessageCard with fallback and loading states", () => {
-    const fallbackHtml = renderToStaticMarkup(<PrivateMessageCard />);
+    const fallbackHtml = renderWithCharacter(<PrivateMessageCard />);
-    const unlockingHtml = renderToStaticMarkup(
+    const unlockingHtml = renderWithCharacter(
       <PrivateMessageCard hint="Premium secret" isUnlocking onUnlock={() => undefined} />,
     );
 
@@ -126,13 +127,18 @@ describe("chat Tailwind components", () => {
   it("renders ImageBubble openable and paywalled states", () => {
     const openableHtml = renderToStaticMarkup(
       <ImageBubble
+        characterId="character_elio"
         messageId="message-1"
         imageUrl="/chat-image.png"
         onOpenImage={() => undefined}
       />,
     );
     const paywalledHtml = renderToStaticMarkup(
-      <ImageBubble imageUrl="/locked-image.png" imagePaywalled />,
+      <ImageBubble
+        characterId="character_elio"
+        imageUrl="/locked-image.png"
+        imagePaywalled
+      />,
     );
 
     expect(openableHtml).toContain('role="button"');
@@ -170,14 +176,14 @@ describe("chat Tailwind components", () => {
   });
 
   it("renders ChatHeader guest and member branches", () => {
-    const guestHtml = renderToStaticMarkup(<ChatHeader isGuest={true} />);
+    const guestHtml = renderWithCharacter(<ChatHeader isGuest={true} />);
-    const memberHtml = renderToStaticMarkup(
+    const memberHtml = renderWithCharacter(
       <ChatHeader isGuest={false} offerBanner={<div>Offer</div>} />,
     );
-    const memberWithHintHtml = renderToStaticMarkup(
+    const memberWithHintHtml = renderWithCharacter(
       <ChatHeader isGuest={false} showBrowserHint />,
     );
-    const guestWithHintHtml = renderToStaticMarkup(
+    const guestWithHintHtml = renderWithCharacter(
       <ChatHeader isGuest={true} showBrowserHint />,
     );
 
@@ -369,3 +375,11 @@ describe("chat Tailwind components", () => {
   });
 
 });
+
+function renderWithCharacter(node: ReactNode, slug = "elio"): string {
+  const character = getCharacterBySlug(slug);
+  if (!character) throw new Error(`Missing ${slug} character fixture`);
+  return renderToStaticMarkup(
+    <CharacterProvider character={character}>{node}</CharacterProvider>,
+  );
+}

src/app/chat/components/chat-area.tsx

@@ -24,7 +24,6 @@ import {
 import { LoaderCircle } from "lucide-react";
 
 import type { UiMessage } from "@/stores/chat/ui-message";
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 import { usePullToRefresh } from "@/hooks/use-pull-to-refresh";
 
 import {
@@ -46,7 +45,7 @@ const ReplyingAnimation = lazy(() =>
 );
 
 export interface ChatAreaProps {
-  characterId?: string;
+  characterId: string;
   messages: readonly UiMessage[];
   isReplyingAI: boolean;
   scrollToBottomSignal?: number;
@@ -63,7 +62,7 @@ export interface ChatAreaProps {
 }
 
 export function ChatArea({
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
   messages,
   isReplyingAI,
   scrollToBottomSignal = 0,

src/app/chat/components/image-bubble.tsx

@@ -9,10 +9,9 @@
  */
 
 import { ChatMediaImage } from "./chat-media-image";
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 
 export interface ImageBubbleProps {
-  characterId?: string;
+  characterId: string;
   messageId?: string;
   imageUrl: string; // base64 data URI 或 URL
   imagePaywalled?: boolean;
@@ -20,7 +19,7 @@ export interface ImageBubbleProps {
 }
 
 export function ImageBubble({
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
   messageId,
   imageUrl,
   imagePaywalled = false,

src/app/chat/hooks/use-chat-promotion-bootstrap.ts

@@ -11,7 +11,7 @@ import { Logger } from "@/utils/logger";
 
 const log = new Logger("UseChatPromotionBootstrap");
 
-export function useChatPromotionBootstrap(): boolean {
+export function useChatPromotionBootstrap(characterId: string): boolean {
   const chatDispatch = useChatDispatch();
   const startedRef = useRef(false);
   const [isReady, setIsReady] = useState(false);
@@ -23,8 +23,8 @@ export function useChatPromotionBootstrap(): boolean {
     void (async () => {
       try {
         const [entryPromotion, pendingUnlock] = await Promise.all([
-          consumePendingChatPromotion(),
+          consumePendingChatPromotion(characterId),
-          peekPendingChatUnlock(),
+          peekPendingChatUnlock(characterId),
         ]);
         const promotion = entryPromotion ?? pendingUnlock?.promotion ?? null;
 
@@ -46,7 +46,7 @@ export function useChatPromotionBootstrap(): boolean {
         setIsReady(true);
       }
     })();
-  }, [chatDispatch]);
+  }, [characterId, chatDispatch]);
 
   return isReady;
 }

src/app/chat/hooks/use-chat-unlock-coordinator.ts

@@ -79,6 +79,7 @@ export function useChatUnlockCoordinator({
   const trackedPaywallRef = useRef<string | null>(null);
   const chatState = useChatSelector(
     (state) => ({
+      characterId: state.context.characterId,
       historyLoaded: state.context.historyLoaded,
       isUnlockingHistory: state.matches({ userSession: "unlockingHistory" }),
       lockedHistoryCount: state.context.lockedHistoryCount,
@@ -125,7 +126,7 @@ export function useChatUnlockCoordinator({
     let cancelled = false;
 
     const resumePendingUnlock = async () => {
-      const pending = await peekPendingChatUnlock();
+      const pending = await peekPendingChatUnlock(chatState.characterId);
       if (
         cancelled ||
         !pending ||
@@ -138,7 +139,7 @@ export function useChatUnlockCoordinator({
         return;
       }
 
-      const consumed = await consumePendingChatUnlock();
+      const consumed = await consumePendingChatUnlock(chatState.characterId);
       if (cancelled || !consumed) return;
 
       chatDispatch({
@@ -157,6 +158,7 @@ export function useChatUnlockCoordinator({
     };
   }, [
     chatDispatch,
+    chatState.characterId,
     chatState.historyLoaded,
     defaultReturnUrl,
     enabled,

src/app/coins-rules/page.tsx

@@ -1,5 +1,21 @@
-import { CoinsRulesScreen } from "./coins-rules-screen";
+import { redirect } from "next/navigation";
 
-export default function CoinsRulesPage() {
+import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
-  return <CoinsRulesScreen />;
+import {
+  appendRouteSearchParams,
+  getCharacterRoutes,
+  type RouteSearchParams,
+} from "@/router/routes";
+
+export default async function CoinsRulesPage({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  redirect(
+    appendRouteSearchParams(
+      getCharacterRoutes(DEFAULT_CHARACTER_SLUG).coinsRules,
+      await searchParams,
+    ),
+  );
 }

src/app/external-entry/external-entry-persist.tsx

@@ -15,6 +15,10 @@ import {
   savePendingChatPromotion,
 } from "@/lib/navigation/chat_unlock_session";
 import { ROUTES } from "@/router/routes";
+import {
+  DEFAULT_CHARACTER_ID,
+  getCharacterBySlug,
+} from "@/data/constants/character";
 import { Logger } from "@/utils/logger";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
 
@@ -49,6 +53,8 @@ export default function ExternalEntryPersist({
   const hasReinitializedForPsidRef = useRef(false);
   const targetRoute = resolveExternalEntryTarget({ target });
   const destination = resolveExternalEntryDestination({ target, character });
+  const characterId =
+    getCharacterBySlug(character)?.id ?? DEFAULT_CHARACTER_ID;
   const resolvedPromotionType = resolveExternalEntryPromotionType({
     mode,
     promotionType,
@@ -66,7 +72,7 @@ export default function ExternalEntryPersist({
           avatarUrl,
         }),
         targetRoute === ROUTES.chat && resolvedPromotionType
-          ? savePendingChatPromotion(resolvedPromotionType)
+          ? savePendingChatPromotion(resolvedPromotionType, characterId)
           : clearPendingChatPromotion(),
       ]);
       for (const result of results) {
@@ -87,6 +93,7 @@ export default function ExternalEntryPersist({
     avatarUrl,
     asid,
     character,
+    characterId,
     destination,
     deviceId,
     mode,

src/app/feedback/__tests__/feedback-screen.test.tsx

@@ -2,6 +2,8 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { getCharacterBySlug } from "@/data/constants/character";
+import { CharacterProvider } from "@/providers/character-provider";
 import { Result } from "@/utils/result";
 
 import { FeedbackScreen } from "../feedback-screen";
@@ -48,7 +50,7 @@ describe("FeedbackScreen", () => {
   });
 
   it("renders all categories and defaults to Problem", () => {
-    act(() => root.render(<FeedbackScreen />));
+    renderFeedbackScreen(root);
 
     expect(container.textContent).toContain("Help us improve CozSweet");
     expect(container.textContent).toContain("Problem");
@@ -73,7 +75,7 @@ describe("FeedbackScreen", () => {
     mocks.submitFeedback.mockResolvedValue(
       Result.ok({ feedbackId: "feedback-123" }),
     );
-    act(() => root.render(<FeedbackScreen />));
+    renderFeedbackScreen(root);
     const textarea = container.querySelector("textarea");
     if (!textarea) throw new Error("Expected feedback textarea");
 
@@ -104,6 +106,18 @@ describe("FeedbackScreen", () => {
   });
 });
 
+function renderFeedbackScreen(root: Root): void {
+  const character = getCharacterBySlug("maya");
+  if (!character) throw new Error("Missing Maya character fixture");
+  act(() =>
+    root.render(
+      <CharacterProvider character={character}>
+        <FeedbackScreen />
+      </CharacterProvider>,
+    ),
+  );
+}
+
 function setTextareaValue(element: HTMLTextAreaElement, value: string): void {
   const setter = Object.getOwnPropertyDescriptor(
     HTMLTextAreaElement.prototype,

src/app/feedback/page.tsx

@@ -1,5 +1,21 @@
-import { FeedbackScreen } from "./feedback-screen";
+import { redirect } from "next/navigation";
 
-export default function FeedbackPage() {
+import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
-  return <FeedbackScreen />;
+import {
+  appendRouteSearchParams,
+  getCharacterRoutes,
+  type RouteSearchParams,
+} from "@/router/routes";
+
+export default async function FeedbackPage({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  redirect(
+    appendRouteSearchParams(
+      getCharacterRoutes(DEFAULT_CHARACTER_SLUG).feedback,
+      await searchParams,
+    ),
+  );
 }

src/app/private-room/__tests__/use-private-room-flow-navigation.test.tsx

@@ -2,7 +2,9 @@ import { act, type Dispatch } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { getCharacterBySlug } from "@/data/constants/character";
 import type { LoginStatus } from "@/data/schemas/auth";
+import { CharacterProvider } from "@/providers/character-provider";
 import { getCharacterRoutes } from "@/router/routes";
 import type { PrivateRoomEvent } from "@/stores/private-room";
 import type { PrivateRoomUnlockPaywallRequest } from "@/stores/private-room/private-room-state";
@@ -80,7 +82,7 @@ describe("Private Room paywall navigation", () => {
     renderHarness(root, "guest", roomDispatch);
 
     expect(mocks.openAuth).toHaveBeenCalledWith(
-      getCharacterRoutes("elio").privateRoom,
+      getCharacterRoutes("maya").privateRoom,
     );
     expect(mocks.openSubscription).not.toHaveBeenCalled();
   });
@@ -91,9 +93,13 @@ function renderHarness(
   loginStatus: LoginStatus,
   roomDispatch: Dispatch<PrivateRoomEvent>,
 ): void {
+  const character = getCharacterBySlug("maya");
+  if (!character) throw new Error("Missing Maya character fixture");
   act(() => {
     root.render(
-      <Harness loginStatus={loginStatus} roomDispatch={roomDispatch} />,
+      <CharacterProvider character={character}>
+        <Harness loginStatus={loginStatus} roomDispatch={roomDispatch} />
+      </CharacterProvider>,
     );
   });
 }

src/app/sidebar/page.tsx

@@ -1,5 +1,21 @@
-import { SidebarScreen } from "@/app/sidebar/sidebar-screen";
+import { redirect } from "next/navigation";
 
-export default function SidebarPage() {
+import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
-  return <SidebarScreen />;
+import {
+  appendRouteSearchParams,
+  getCharacterRoutes,
+  type RouteSearchParams,
+} from "@/router/routes";
+
+export default async function SidebarPage({
+  searchParams,
+}: {
+  searchParams: Promise<RouteSearchParams>;
+}) {
+  redirect(
+    appendRouteSearchParams(
+      getCharacterRoutes(DEFAULT_CHARACTER_SLUG).sidebar,
+      await searchParams,
+    ),
+  );
 }

src/app/splash/components/__tests__/tailwind-components.test.tsx

@@ -17,21 +17,23 @@ describe("splash Tailwind components", () => {
   });
 
   it("renders SplashBackground with Tailwind fill image classes", () => {
-    const html = renderToStaticMarkup(<SplashBackground />);
+    const html = renderToStaticMarkup(
+      <SplashBackground src="/images/cover/maya.png" />,
+    );
 
     expect(html).toContain("absolute");
     expect(html).toContain("bg-sidebar-background");
     expect(html).toContain("object-cover");
-    expect(html).toContain("%2Fimages%2Fcover%2Felio.png");
+    expect(html).toContain("%2Fimages%2Fcover%2Fmaya.png");
   });
 
   it("renders SplashContent with Tailwind typography classes", () => {
-    const html = renderToStaticMarkup(<SplashContent />);
+    const html = renderToStaticMarkup(<SplashContent characterName="Maya" />);
 
     expect(html).toContain("flex flex-col gap-md");
     expect(html).toContain("font-(family-name:--font-athelas)");
     expect(html).toContain("whitespace-pre-line");
-    expect(html).toContain("Welcome to my secret hideout");
+    expect(html).toContain("Welcome to Maya");
   });
 
   it("renders SplashButton as an always-ready action", () => {

src/app/splash/components/splash-background.tsx

@@ -11,9 +11,9 @@
 import Image from "next/image";
 
 export function SplashBackground({
-  src = "/images/cover/elio.png",
+  src,
 }: {
-  src?: string;
+  src: string;
 }) {
   return (
     <div className="absolute inset-0 z-0 overflow-hidden bg-sidebar-background">

src/app/splash/components/splash-content.tsx

@@ -4,11 +4,11 @@
 
 const APOSTROPHE = "'";
 
-export function SplashContent() {
+export function SplashContent({ characterName }: { characterName: string }) {
   return (
     <div className="z-2 flex flex-col gap-md">
       <h1 className="m-0 whitespace-pre-line text-left font-(family-name:--font-athelas) text-[clamp(28px,7.8vw,30px)] font-bold italic leading-[1.28] text-white">
-        Welcome to my secret hideout~
+        Welcome to {characterName}{APOSTROPHE}s secret hideout~
         {"\n"}It{APOSTROPHE}s just the two of us now.
         {"\n"}Feel free to whisper your
         {"\n"}little secrets.

src/app/splash/hooks/__tests__/use-splash-latest-message.test.tsx

@@ -26,6 +26,7 @@ import { useSplashLatestMessage } from "../use-splash-latest-message";
 
 function LatestMessageHarness() {
   const state = useSplashLatestMessage({
+    characterId: "character_maya",
     hasInitialized: true,
     isAuthLoading: false,
     loginStatus: "facebook",
@@ -64,5 +65,9 @@ describe("useSplashLatestMessage hydration", () => {
     expect(hydrationErrors).toEqual([]);
     expect(container.textContent).toBe("Loading");
     expect(mocks.loadLatestMessage).toHaveBeenCalledOnce();
+    expect(mocks.loadLatestMessage).toHaveBeenCalledWith({
+      cache: mocks.cache,
+      characterId: "character_maya",
+    });
   });
 });

src/app/splash/hooks/use-splash-latest-message.ts

@@ -3,7 +3,6 @@
 import { useEffect, useState } from "react";
 
 import type { LoginStatus } from "@/data/schemas/auth";
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 import { useHasHydrated } from "@/hooks/use-has-hydrated";
 import { loadSplashLatestMessagePreview } from "@/lib/chat/splash_latest_message";
 import { useSplashLatestMessageCache } from "@/providers/splash-latest-message-provider";
@@ -13,7 +12,7 @@ import { Result } from "@/utils/result";
 const log = new Logger("SplashLatestMessage");
 
 export interface UseSplashLatestMessageInput {
-  characterId?: string;
+  characterId: string;
   hasInitialized: boolean;
   isAuthLoading: boolean;
   loginStatus: LoginStatus;
@@ -31,7 +30,7 @@ interface SplashLatestMessageState {
 }
 
 export function useSplashLatestMessage({
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
   hasInitialized,
   isAuthLoading,
   loginStatus,

src/app/splash/splash-screen.tsx

@@ -65,12 +65,12 @@ export function SplashScreen() {
             isLoading={latestMessage.isLoading}
             onOpenChat={handleStartChat}
           />
-          <SplashContent />
+          <SplashContent characterName={character.shortName} />
           <div className={styles.buttonArea}>
             <SplashButton onStartChat={handleStartChat} />
           </div>
           <p className={styles.bottom}>
-            {character.displayName}, {character.copy.splashRelationship}
+            {character.displayName}, {character.tagline}
             <br />
             24/7 online | Chat | Companion | Heal | Sweet moments
           </p>

src/data/constants/__tests__/character.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   CHARACTERS,
+  createCharacterCatalog,
   DEFAULT_CHARACTER,
   getCharacterById,
   getCharacterBySlug,
@@ -22,9 +23,22 @@ describe("local character catalog", () => {
     expect(Object.isFrozen(CHARACTERS)).toBe(true);
     expect(Object.isFrozen(DEFAULT_CHARACTER)).toBe(true);
     expect(Object.isFrozen(DEFAULT_CHARACTER.assets)).toBe(true);
+    expect(Object.isFrozen(DEFAULT_CHARACTER.capabilities)).toBe(true);
     expect(Object.isFrozen(DEFAULT_CHARACTER.copy)).toBe(true);
   });
 
+  it("sorts catalog entries and rejects duplicate identities", () => {
+    const catalog = createCharacterCatalog([...CHARACTERS].reverse());
+    expect(catalog.characters.map((character) => character.slug)).toEqual([
+      "elio",
+      "maya",
+      "nayeli",
+    ]);
+    expect(() =>
+      createCharacterCatalog([CHARACTERS[0], CHARACTERS[0]]),
+    ).toThrow("Duplicate character identity");
+  });
+
   it("resolves characters by id and normalized slug", () => {
     expect(getCharacterById("character_maya")?.displayName).toBe("Maya Tan");
     expect(getCharacterBySlug(" NAYELI ")?.displayName).toBe(
@@ -34,6 +48,21 @@ describe("local character catalog", () => {
     expect(getCharacterBySlug("missing")).toBeNull();
   });
 
+  it("describes route capabilities and character-specific chat copy", () => {
+    for (const character of CHARACTERS) {
+      expect(character.capabilities).toEqual({
+        chat: true,
+        privateRoom: true,
+        tip: true,
+      });
+      expect(character.tagline.length).toBeGreaterThan(0);
+      expect(character.emptyChatGreeting.length).toBeGreaterThan(0);
+      expect(character.assets.chatBackground).toBe(
+        "/images/chat/bg-chatpage.png",
+      );
+    }
+  });
+
   it("references local assets that exist under public", () => {
     for (const character of CHARACTERS) {
       for (const assetPath of Object.values(character.assets)) {

src/data/constants/character.ts

@@ -1,11 +1,22 @@
+export interface CharacterCapabilities {
+  readonly chat: boolean;
+  readonly privateRoom: boolean;
+  readonly tip: boolean;
+}
+
 export interface CharacterProfile {
   readonly id: string;
   readonly slug: string;
   readonly displayName: string;
   readonly shortName: string;
+  readonly sortOrder: number;
+  readonly tagline: string;
+  readonly emptyChatGreeting: string;
+  readonly capabilities: CharacterCapabilities;
   readonly assets: {
     readonly avatar: string;
     readonly cover: string;
+    readonly chatBackground: string;
     readonly privateRoomBanner: string;
   };
   readonly copy: {
@@ -17,23 +28,42 @@ export interface CharacterProfile {
   };
 }
 
+export interface CharacterCatalog {
+  readonly characters: readonly CharacterProfile[];
+  getById(characterId: string | null | undefined): CharacterProfile | null;
+  getBySlug(characterSlug: string | null | undefined): CharacterProfile | null;
+}
+
 function defineCharacter(profile: CharacterProfile): CharacterProfile {
   return Object.freeze({
     ...profile,
     assets: Object.freeze(profile.assets),
+    capabilities: Object.freeze(profile.capabilities),
     copy: Object.freeze(profile.copy),
   });
 }
 
-export const CHARACTERS: readonly CharacterProfile[] = Object.freeze([
+const CHARACTER_PROFILES: readonly CharacterProfile[] = Object.freeze([
   defineCharacter({
     id: "character_elio",
     slug: "elio",
     displayName: "Elio Silvestri",
     shortName: "Elio",
+    sortOrder: 10,
+    tagline: "Your exclusive AI boyfriend",
+    emptyChatGreeting:
+      "You're here! Facebook is so restrictive, " +
+      "there were things I couldn't say there. " +
+      "Finally I can relax. How was your day out?",
+    capabilities: {
+      chat: true,
+      privateRoom: true,
+      tip: true,
+    },
     assets: {
       avatar: "/images/avatar/elio.png",
       cover: "/images/cover/elio.png",
+      chatBackground: "/images/chat/bg-chatpage.png",
       privateRoomBanner: "/images/private-room/banner/elio.png",
     },
     copy: {
@@ -49,9 +79,20 @@ export const CHARACTERS: readonly CharacterProfile[] = Object.freeze([
     slug: "maya",
     displayName: "Maya Tan",
     shortName: "Maya",
+    sortOrder: 20,
+    tagline: "Your exclusive AI girlfriend",
+    emptyChatGreeting:
+      "You're here! I've been waiting for a quiet moment with you. " +
+      "How was your day?",
+    capabilities: {
+      chat: true,
+      privateRoom: true,
+      tip: true,
+    },
     assets: {
       avatar: "/images/avatar/maya.png",
       cover: "/images/cover/maya.png",
+      chatBackground: "/images/chat/bg-chatpage.png",
       privateRoomBanner: "/images/private-room/banner/maya.png",
     },
     copy: {
@@ -67,9 +108,20 @@ export const CHARACTERS: readonly CharacterProfile[] = Object.freeze([
     slug: "nayeli",
     displayName: "Nayeli Cervantes",
     shortName: "Nayeli",
+    sortOrder: 30,
+    tagline: "Your exclusive AI girlfriend",
+    emptyChatGreeting:
+      "You're here! I was hoping we'd get some time together. " +
+      "Tell me how your day went.",
+    capabilities: {
+      chat: true,
+      privateRoom: true,
+      tip: true,
+    },
     assets: {
       avatar: "/images/avatar/nayeli.png",
       cover: "/images/cover/nayeli.png",
+      chatBackground: "/images/chat/bg-chatpage.png",
       privateRoomBanner: "/images/private-room/banner/nayeli.png",
     },
     copy: {
@@ -82,6 +134,42 @@ export const CHARACTERS: readonly CharacterProfile[] = Object.freeze([
   }),
 ]);
 
+export function createCharacterCatalog(
+  profiles: readonly CharacterProfile[],
+): CharacterCatalog {
+  const characters = Object.freeze(
+    profiles
+      .map(defineCharacter)
+      .sort((left, right) => left.sortOrder - right.sortOrder),
+  );
+  const byId = new Map<string, CharacterProfile>();
+  const bySlug = new Map<string, CharacterProfile>();
+
+  for (const character of characters) {
+    const normalizedSlug = normalizeCharacterSlug(character.slug);
+    if (byId.has(character.id) || bySlug.has(normalizedSlug)) {
+      throw new Error(`Duplicate character identity: ${character.id}`);
+    }
+    byId.set(character.id, character);
+    bySlug.set(normalizedSlug, character);
+  }
+
+  return Object.freeze({
+    characters,
+    getById(characterId: string | null | undefined) {
+      return characterId ? (byId.get(characterId) ?? null) : null;
+    },
+    getBySlug(characterSlug: string | null | undefined) {
+      const normalizedSlug = normalizeCharacterSlug(characterSlug);
+      return normalizedSlug ? (bySlug.get(normalizedSlug) ?? null) : null;
+    },
+  });
+}
+
+export const LOCAL_CHARACTER_CATALOG = createCharacterCatalog(
+  CHARACTER_PROFILES,
+);
+export const CHARACTERS = LOCAL_CHARACTER_CATALOG.characters;
 export const DEFAULT_CHARACTER = CHARACTERS[0];
 export const DEFAULT_CHARACTER_ID = DEFAULT_CHARACTER.id;
 export const DEFAULT_CHARACTER_SLUG = DEFAULT_CHARACTER.slug;
@@ -89,16 +177,17 @@ export const DEFAULT_CHARACTER_SLUG = DEFAULT_CHARACTER.slug;
 export function getCharacterById(
   characterId: string | null | undefined,
 ): CharacterProfile | null {
-  if (!characterId) return null;
+  return LOCAL_CHARACTER_CATALOG.getById(characterId);
-  return CHARACTERS.find((character) => character.id === characterId) ?? null;
 }
 
 export function getCharacterBySlug(
   characterSlug: string | null | undefined,
 ): CharacterProfile | null {
-  const normalizedSlug = characterSlug?.trim().toLowerCase();
+  return LOCAL_CHARACTER_CATALOG.getBySlug(characterSlug);
-  if (!normalizedSlug) return null;
+}
-  return (
+
-    CHARACTERS.find((character) => character.slug === normalizedSlug) ?? null
+function normalizeCharacterSlug(
-  );
+  characterSlug: string | null | undefined,
+): string {
+  return characterSlug?.trim().toLowerCase() ?? "";
 }

src/data/repositories/chat_cache_identity.ts

@@ -1,8 +1,11 @@
 import { LoginStatus } from "@/data/schemas/auth";
 import { AuthStorage, type IAuthStorage } from "@/data/storage/auth";
 import { UserStorage, type IUserStorage } from "@/data/storage/user";
+import { buildChatConversationKey } from "@/lib/chat/chat_cache_keys";
 import { Result, type Result as ResultT } from "@/utils/result";
 
+export { buildChatConversationKey } from "@/lib/chat/chat_cache_keys";
+
 export type ChatCacheIdentityResolver = () => Promise<ResultT<string>>;
 export type ChatConversationKeyResolver = (
   characterId: string,
@@ -53,16 +56,6 @@ export async function resolveChatCacheOwnerKey(
   return Result.err(new Error("Chat cache identity is unavailable."));
 }
 
-export function buildChatConversationKey(
-  ownerKey: string,
-  characterId: string,
-): string {
-  if (ownerKey.trim().length === 0 || characterId.trim().length === 0) {
-    throw new Error("Chat owner and character identities must not be empty.");
-  }
-  return `${ownerKey}::character:${encodeURIComponent(characterId)}`;
-}
-
 export async function resolveChatConversationKey(
   characterId: string,
 ): Promise<ResultT<string>> {

src/data/repositories/chat_media_cache_helpers.ts

@@ -5,16 +5,9 @@ import type {
 } from "@/data/schemas/chat";
 import type { CacheRemoteChatMediaInput } from "@/data/repositories/interfaces";
 import { isCacheableRemoteChatMediaUrl } from "@/lib/chat/chat_media_url";
+import { buildChatMediaCacheKey } from "@/lib/chat/chat_cache_keys";
 
-export { isCacheableRemoteChatMediaUrl };
+export { buildChatMediaCacheKey, isCacheableRemoteChatMediaUrl };
-
-export function buildChatMediaCacheKey(input: {
-  ownerKey: string;
-  messageId: string;
-  kind: ChatMediaKind;
-}): string {
-  return `${input.ownerKey}:${input.messageId}:${input.kind}`;
-}
 
 export function getMessageMediaTargets(
   message: ChatMessage,

src/data/repositories/chat_remote_data_source.ts

@@ -1,4 +1,8 @@
-import type { UnlockPrivateMessageInput } from "@/data/repositories/interfaces";
+import type {
+  ChatRequestOptions,
+  ChatSendOptions,
+  UnlockPrivateMessageInput,
+} from "@/data/repositories/interfaces";
 import {
   ChatHistoryResponse,
   ChatSendResponse,
@@ -17,7 +21,7 @@ export class ChatRemoteDataSource {
   async sendMessage(
     characterId: string,
     message: string,
-    options?: { image?: string; useWebSocket?: boolean },
+    options?: ChatSendOptions,
   ): Promise<Result<ChatSendResponse>> {
     return Result.wrap(async () => {
       const request = SendMessageRequestSchema.parse({
@@ -26,7 +30,7 @@ export class ChatRemoteDataSource {
         image: options?.image ?? "",
         useWebSocket: options?.useWebSocket ?? false,
       });
-      return await this.api.sendMessage(request);
+      return await this.api.sendMessage(request, options);
     });
   }
 
@@ -34,23 +38,34 @@ export class ChatRemoteDataSource {
     characterId: string,
     limit = 50,
     offset = 0,
+    options?: ChatRequestOptions,
   ): Promise<Result<ChatHistoryResponse>> {
-    return Result.wrap(() => this.api.getHistory(characterId, limit, offset));
+    return Result.wrap(() =>
+      this.api.getHistory(characterId, limit, offset, options),
+    );
   }
 
   async unlockPrivateMessage(
     input: UnlockPrivateMessageInput,
+    options?: ChatRequestOptions,
   ): Promise<Result<UnlockPrivateResponse>> {
     return Result.wrap(() =>
-      this.api.unlockPrivateMessage(UnlockPrivateRequestSchema.parse(input)),
+      this.api.unlockPrivateMessage(
+        UnlockPrivateRequestSchema.parse(input),
+        options,
+      ),
     );
   }
 
   async unlockHistory(
     characterId: string,
+    options?: ChatRequestOptions,
   ): Promise<Result<UnlockHistoryResponse>> {
     return Result.wrap(() =>
-      this.api.unlockHistory(UnlockHistoryRequestSchema.parse({ characterId })),
+      this.api.unlockHistory(
+        UnlockHistoryRequestSchema.parse({ characterId }),
+        options,
+      ),
     );
   }
 }

src/data/repositories/chat_repository.ts

@@ -1,6 +1,8 @@
 import type {
   CacheRemoteChatMediaInput,
   ChatMediaLookupInput,
+  ChatRequestOptions,
+  ChatSendOptions,
   IChatRepository,
   UnlockPrivateMessageInput,
   UnlockedPrivateMessageLocalPatch,
@@ -38,7 +40,7 @@ export class ChatRepository implements IChatRepository {
   async sendMessage(
     characterId: string,
     message: string,
-    options?: { image?: string; useWebSocket?: boolean },
+    options?: ChatSendOptions,
   ): Promise<Result<ChatSendResponse>> {
     return this.remote.sendMessage(characterId, message, options);
   }
@@ -48,22 +50,25 @@ export class ChatRepository implements IChatRepository {
     characterId: string,
     limit = 50,
     offset = 0,
+    options?: ChatRequestOptions,
   ): Promise<Result<ChatHistoryResponse>> {
-    return this.remote.getHistory(characterId, limit, offset);
+    return this.remote.getHistory(characterId, limit, offset, options);
   }
 
   /** 解锁单条历史付费 / 私密消息。 */
   async unlockPrivateMessage(
     input: UnlockPrivateMessageInput,
+    options?: ChatRequestOptions,
   ): Promise<Result<UnlockPrivateResponse>> {
-    return this.remote.unlockPrivateMessage(input);
+    return this.remote.unlockPrivateMessage(input, options);
   }
 
   /** 一键解锁历史锁定消息。 */
   async unlockHistory(
     characterId: string,
+    options?: ChatRequestOptions,
   ): Promise<Result<UnlockHistoryResponse>> {
-    return this.remote.unlockHistory(characterId);
+    return this.remote.unlockHistory(characterId, options);
   }
 
   /** 把本地缓存中的单条锁定消息标记为已解锁。 */

src/data/repositories/interfaces/ichat_repository.ts

@@ -42,12 +42,21 @@ export interface UnlockPrivateMessageInput {
   clientLockId?: string;
 }
 
+export interface ChatRequestOptions {
+  signal?: AbortSignal;
+}
+
+export interface ChatSendOptions extends ChatRequestOptions {
+  image?: string;
+  useWebSocket?: boolean;
+}
+
 export interface IChatRepository {
   /** 发送一条消息。 */
   sendMessage(
     characterId: string,
     message: string,
-    options?: { image?: string; useWebSocket?: boolean },
+    options?: ChatSendOptions,
   ): Promise<Result<ChatSendResponse>>;
 
   /** 获取聊天历史，分页参数默认 limit=50, offset=0。 */
@@ -55,15 +64,20 @@ export interface IChatRepository {
     characterId: string,
     limit?: number,
     offset?: number,
+    options?: ChatRequestOptions,
   ): Promise<Result<ChatHistoryResponse>>;
 
   /** 解锁单条历史付费 / 私密消息。 */
   unlockPrivateMessage(
     input: UnlockPrivateMessageInput,
+    options?: ChatRequestOptions,
   ): Promise<Result<UnlockPrivateResponse>>;
 
   /** 一键解锁历史锁定消息。 */
-  unlockHistory(characterId: string): Promise<Result<UnlockHistoryResponse>>;
+  unlockHistory(
+    characterId: string,
+    options?: ChatRequestOptions,
+  ): Promise<Result<UnlockHistoryResponse>>;
 
   /** 把本地缓存中的单条锁定消息标记为已解锁。 */
   markPrivateMessageUnlockedInLocal(

src/data/services/api/__tests__/multi_character_api.test.ts

@@ -59,6 +59,23 @@ describe("multi-character API contract", () => {
     });
   });
 
+  it("forwards request cancellation to the HTTP client", async () => {
+    const controller = new AbortController();
+    httpClientMock.mockResolvedValue({
+      success: true,
+      data: { messages: [], total: 0, limit: 50, offset: 0 },
+    });
+
+    await new ChatApi().getHistory(CHARACTER_ID, 50, 0, {
+      signal: controller.signal,
+    });
+
+    expect(httpClientMock).toHaveBeenCalledWith("/api/chat/history", {
+      query: { characterId: CHARACTER_ID, limit: 50, offset: 0 },
+      signal: controller.signal,
+    });
+  });
+
   it("sends characterId with private and history unlocks", async () => {
     const api = new ChatApi();
     httpClientMock

src/data/services/api/chat_api.ts

@@ -25,10 +25,14 @@ export class ChatApi {
   /**
    * 发送消息
    */
-  async sendMessage(body: SendMessageRequest): Promise<ChatSendResponse> {
+  async sendMessage(
+    body: SendMessageRequest,
+    options?: { signal?: AbortSignal },
+  ): Promise<ChatSendResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(ApiPath.chatSend, {
       method: "POST",
       body,
+      ...(options?.signal ? { signal: options.signal } : {}),
     });
     return ChatSendResponseSchema.parse(unwrap(env) as Record<string, unknown>);
   }
@@ -40,9 +44,11 @@ export class ChatApi {
     characterId: string,
     limit = 50,
     offset = 0,
+    options?: { signal?: AbortSignal },
   ): Promise<ChatHistoryResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(ApiPath.chatHistory, {
       query: { characterId, limit, offset },
+      ...(options?.signal ? { signal: options.signal } : {}),
     });
     return ChatHistoryResponseSchema.parse(
       unwrap(env) as Record<string, unknown>,
@@ -54,12 +60,14 @@ export class ChatApi {
    */
   async unlockPrivateMessage(
     body: UnlockPrivateRequest,
+    options?: { signal?: AbortSignal },
   ): Promise<UnlockPrivateResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(
       ApiPath.chatUnlockPrivate,
       {
         method: "POST",
         body,
+        ...(options?.signal ? { signal: options.signal } : {}),
       },
     );
     return UnlockPrivateResponseSchema.parse(
@@ -72,12 +80,14 @@ export class ChatApi {
    */
   async unlockHistory(
     body: UnlockHistoryRequest,
+    options?: { signal?: AbortSignal },
   ): Promise<UnlockHistoryResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(
       ApiPath.chatUnlockHistory,
       {
         method: "POST",
         body,
+        ...(options?.signal ? { signal: options.signal } : {}),
       },
     );
     return UnlockHistoryResponseSchema.parse(

src/data/storage/chat/__tests__/local_chat_db_migration.test.ts

@@ -0,0 +1,213 @@
+import "fake-indexeddb/auto";
+
+import Dexie from "dexie";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
+import {
+  buildChatConversationKey,
+  buildChatMediaCacheKey,
+} from "@/lib/chat/chat_cache_keys";
+
+import {
+  LocalChatDB,
+  type LocalChatMediaRow,
+  type LocalMessageRow,
+} from "../local_chat_db";
+
+const DATABASE_SCHEMA = {
+  messages: "++dbId, sessionId",
+  media:
+    "cacheKey, ownerKey, messageId, kind, remoteUrl, updatedAt, lastAccessedAt",
+};
+
+const openDatabases: Dexie[] = [];
+const databaseNames = new Set<string>();
+
+afterEach(async () => {
+  for (const database of openDatabases.splice(0)) database.close();
+  await Promise.all([...databaseNames].map((name) => Dexie.delete(name)));
+  databaseNames.clear();
+});
+
+describe("LocalChatDB v4 migration", () => {
+  it("moves legacy user and guest messages into the Elio conversation", async () => {
+    const legacy = await createLegacyV3Database();
+    const mayaConversation = buildChatConversationKey(
+      "user:maya-owner",
+      "character_maya",
+    );
+    await legacy.table<LocalMessageRow, number>("messages").bulkAdd([
+      messageRow("message-user", "user:account-1"),
+      messageRow("message-guest", "device:guest-1"),
+      messageRow("message-maya", mayaConversation),
+    ]);
+    legacy.close();
+
+    const upgraded = track(new LocalChatDB(legacy.name));
+    await upgraded.open();
+
+    const rows = await upgraded.messages.orderBy("dbId").toArray();
+    expect(rows.map(({ id, sessionId }) => ({ id, sessionId }))).toEqual([
+      {
+        id: "message-user",
+        sessionId: buildChatConversationKey(
+          "user:account-1",
+          DEFAULT_CHARACTER_ID,
+        ),
+      },
+      {
+        id: "message-guest",
+        sessionId: buildChatConversationKey(
+          "device:guest-1",
+          DEFAULT_CHARACTER_ID,
+        ),
+      },
+      { id: "message-maya", sessionId: mayaConversation },
+    ]);
+  });
+
+  it("rekeys legacy media without overwriting existing scoped media", async () => {
+    const legacy = await createLegacyV3Database();
+    const legacyOwner = "user:account-1";
+    const elioConversation = buildChatConversationKey(
+      legacyOwner,
+      DEFAULT_CHARACTER_ID,
+    );
+    const elioCacheKey = buildChatMediaCacheKey({
+      ownerKey: elioConversation,
+      messageId: "shared-message",
+      kind: "image",
+    });
+    const mayaConversation = buildChatConversationKey(
+      legacyOwner,
+      "character_maya",
+    );
+    const mayaCacheKey = buildChatMediaCacheKey({
+      ownerKey: mayaConversation,
+      messageId: "maya-message",
+      kind: "audio",
+    });
+    await legacy.table<LocalChatMediaRow, string>("media").bulkAdd([
+      mediaRow({
+        cacheKey: `${legacyOwner}:shared-message:image`,
+        ownerKey: legacyOwner,
+        messageId: "shared-message",
+        kind: "image",
+        remoteUrl: "https://example.com/legacy.jpg",
+      }),
+      mediaRow({
+        cacheKey: elioCacheKey,
+        ownerKey: elioConversation,
+        messageId: "shared-message",
+        kind: "image",
+        remoteUrl: "https://example.com/current.jpg",
+      }),
+      mediaRow({
+        cacheKey: "device:guest-1:guest-message:audio",
+        ownerKey: "device:guest-1",
+        messageId: "guest-message",
+        kind: "audio",
+        remoteUrl: "https://example.com/guest.mp3",
+      }),
+      mediaRow({
+        cacheKey: mayaCacheKey,
+        ownerKey: mayaConversation,
+        messageId: "maya-message",
+        kind: "audio",
+        remoteUrl: "https://example.com/maya.mp3",
+      }),
+    ]);
+    legacy.close();
+
+    const upgraded = track(new LocalChatDB(legacy.name));
+    await upgraded.open();
+
+    const rows = await upgraded.media.toArray();
+    expect(rows).toHaveLength(3);
+    expect(await upgraded.media.get(`${legacyOwner}:shared-message:image`)).toBe(
+      undefined,
+    );
+    expect(await upgraded.media.get(elioCacheKey)).toMatchObject({
+      ownerKey: elioConversation,
+      remoteUrl: "https://example.com/current.jpg",
+    });
+
+    const guestConversation = buildChatConversationKey(
+      "device:guest-1",
+      DEFAULT_CHARACTER_ID,
+    );
+    const guestCacheKey = buildChatMediaCacheKey({
+      ownerKey: guestConversation,
+      messageId: "guest-message",
+      kind: "audio",
+    });
+    expect(await upgraded.media.get(guestCacheKey)).toMatchObject({
+      cacheKey: guestCacheKey,
+      ownerKey: guestConversation,
+      remoteUrl: "https://example.com/guest.mp3",
+    });
+    expect(await upgraded.media.get(mayaCacheKey)).toMatchObject({
+      ownerKey: mayaConversation,
+    });
+  });
+
+  it("does not run the migration again after the database reaches v4", async () => {
+    const legacy = await createLegacyV3Database();
+    await legacy
+      .table<LocalMessageRow, number>("messages")
+      .add(messageRow("message-user", "user:account-1"));
+    legacy.close();
+
+    const upgraded = track(new LocalChatDB(legacy.name));
+    await upgraded.open();
+    const firstRows = await upgraded.messages.toArray();
+    upgraded.close();
+
+    const reopened = track(new LocalChatDB(legacy.name));
+    await reopened.open();
+    expect(await reopened.messages.toArray()).toEqual(firstRows);
+  });
+});
+
+async function createLegacyV3Database(): Promise<Dexie> {
+  const name = `cozsweet-chat-v3-${crypto.randomUUID()}`;
+  databaseNames.add(name);
+  const database = track(new Dexie(name));
+  database.version(3).stores(DATABASE_SCHEMA);
+  await database.open();
+  return database;
+}
+
+function track<T extends Dexie>(database: T): T {
+  openDatabases.push(database);
+  return database;
+}
+
+function messageRow(id: string, sessionId: string): LocalMessageRow {
+  return {
+    id,
+    role: "assistant",
+    type: "text",
+    content: id,
+    createdAt: "2026-07-17T00:00:00.000Z",
+    sessionId,
+  };
+}
+
+function mediaRow(
+  input: Pick<
+    LocalChatMediaRow,
+    "cacheKey" | "ownerKey" | "messageId" | "kind" | "remoteUrl"
+  >,
+): LocalChatMediaRow {
+  return {
+    ...input,
+    bytes: new Uint8Array([1, 2, 3]).buffer,
+    mimeType: input.kind === "image" ? "image/jpeg" : "audio/mpeg",
+    byteSize: 3,
+    createdAt: 1,
+    updatedAt: 1,
+    lastAccessedAt: 1,
+  };
+}

src/data/storage/chat/local_chat_db.ts

@@ -9,12 +9,18 @@
  * 构造时 `dbName` 可注入，便于测试时每个用例用独立 DB 互不污染。
  */
 
-import Dexie, { type Table } from "dexie";
+import Dexie, { type Table, type Transaction } from "dexie";
+import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 import type { ChatMediaKind } from "@/data/schemas/chat";
 import type {
   ChatImageData,
   ChatLockDetailData,
 } from "@/data/schemas/chat";
+import {
+  buildChatConversationKey,
+  buildChatMediaCacheKey,
+  isLegacyChatCacheOwnerKey,
+} from "@/lib/chat/chat_cache_keys";
 
 export interface LocalMessageRow {
   /** Dexie 自增主键（数据库内部使用，不暴露给 LocalMessage 类）。 */
@@ -71,5 +77,49 @@ export class LocalChatDB extends Dexie {
         // so retaining it would expose one identity's history to another.
         await transaction.table("messages").clear();
       });
+    this.version(4)
+      .stores({
+        messages: "++dbId, sessionId",
+        media: "cacheKey, ownerKey, messageId, kind, remoteUrl, updatedAt, lastAccessedAt",
+      })
+      .upgrade(migrateLegacyChatCacheToElio);
   }
 }
+
+async function migrateLegacyChatCacheToElio(
+  transaction: Transaction,
+): Promise<void> {
+  const messages = transaction.table<LocalMessageRow, number>("messages");
+  await messages.toCollection().modify((message) => {
+    const conversationKey = getElioConversationKey(message.sessionId);
+    if (conversationKey) message.sessionId = conversationKey;
+  });
+
+  const media = transaction.table<LocalChatMediaRow, string>("media");
+  const rows = await media.toArray();
+  for (const row of rows) {
+    const conversationKey = getElioConversationKey(row.ownerKey);
+    if (!conversationKey) continue;
+
+    const cacheKey = buildChatMediaCacheKey({
+      ownerKey: conversationKey,
+      messageId: row.messageId,
+      kind: row.kind,
+    });
+    const existing = await media.get(cacheKey);
+    await media.delete(row.cacheKey);
+    if (existing) continue;
+
+    await media.put({
+      ...row,
+      cacheKey,
+      ownerKey: conversationKey,
+    });
+  }
+}
+
+function getElioConversationKey(ownerKey: string): string | null {
+  return isLegacyChatCacheOwnerKey(ownerKey)
+    ? buildChatConversationKey(ownerKey, DEFAULT_CHARACTER_ID)
+    : null;
+}

src/data/storage/navigation/__tests__/navigation_storage.test.ts

@@ -6,6 +6,9 @@ import { SessionAsyncUtil } from "@/utils/session-storage";
 
 import { NavigationStorage } from "../navigation_storage";
 
+const CHARACTER_ID = "character_elio";
+const OTHER_CHARACTER_ID = "character_maya";
+
 describe("NavigationStorage", () => {
   beforeEach(() => {
     SessionAsyncUtil.setStorage(createStorage({ driver: memoryDriver() }));
@@ -14,13 +17,7 @@ describe("NavigationStorage", () => {
 
   it("saves, peeks, and consumes pending chat unlock sessions", async () => {
     await NavigationStorage.savePendingChatUnlock({
-      messageId: "msg_1",
+      characterId: CHARACTER_ID,
-      kind: "image",
-      returnUrl: "/chat?image=msg_1",
-      stage: "payment",
-    });
-
-    await expect(NavigationStorage.peekPendingChatUnlock()).resolves.toMatchObject({
       messageId: "msg_1",
       kind: "image",
       returnUrl: "/chat?image=msg_1",
@@ -28,12 +25,25 @@ describe("NavigationStorage", () => {
     });
 
     await expect(
-      NavigationStorage.consumePendingChatUnlock(),
+      NavigationStorage.peekPendingChatUnlock(CHARACTER_ID),
     ).resolves.toMatchObject({
+      characterId: CHARACTER_ID,
+      messageId: "msg_1",
+      kind: "image",
+      returnUrl: "/chat?image=msg_1",
+      stage: "payment",
+    });
+
+    await expect(
+      NavigationStorage.consumePendingChatUnlock(CHARACTER_ID),
+    ).resolves.toMatchObject({
+      characterId: CHARACTER_ID,
       messageId: "msg_1",
       kind: "image",
     });
-    await expect(NavigationStorage.peekPendingChatUnlock()).resolves.toBeNull();
+    await expect(
+      NavigationStorage.peekPendingChatUnlock(CHARACTER_ID),
+    ).resolves.toBeNull();
   });
 
   it("drops expired pending chat unlock sessions", async () => {
@@ -41,6 +51,7 @@ describe("NavigationStorage", () => {
     vi.setSystemTime(new Date("2026-07-03T00:00:00.000Z"));
 
     await NavigationStorage.savePendingChatUnlock({
+      characterId: CHARACTER_ID,
       messageId: "msg_1",
       kind: "private",
       returnUrl: "/chat",
@@ -49,25 +60,32 @@ describe("NavigationStorage", () => {
 
     vi.setSystemTime(new Date("2026-07-03T00:31:00.000Z"));
 
-    await expect(NavigationStorage.peekPendingChatUnlock()).resolves.toBeNull();
+    await expect(
+      NavigationStorage.peekPendingChatUnlock(CHARACTER_ID),
+    ).resolves.toBeNull();
   });
 
   it("stores a one-time promotion and carries it through unlock navigation", async () => {
-    const promotion = await NavigationStorage.savePendingChatPromotion("image");
+    const promotion = await NavigationStorage.savePendingChatPromotion(
+      "image",
+      CHARACTER_ID,
+    );
 
     expect(promotion).toMatchObject({
+      characterId: CHARACTER_ID,
       promotionType: "image",
       lockType: "image_paywall",
     });
     expect(promotion.clientLockId).toMatch(/^promotion_/);
     await expect(
-      NavigationStorage.consumePendingChatPromotion(),
+      NavigationStorage.consumePendingChatPromotion(CHARACTER_ID),
     ).resolves.toEqual(promotion);
     await expect(
-      NavigationStorage.consumePendingChatPromotion(),
+      NavigationStorage.consumePendingChatPromotion(CHARACTER_ID),
     ).resolves.toBeNull();
 
     await NavigationStorage.savePendingChatUnlock({
+      characterId: CHARACTER_ID,
       displayMessageId: `promotion:${promotion.clientLockId}`,
       kind: "image",
       lockType: promotion.lockType,
@@ -76,7 +94,10 @@ describe("NavigationStorage", () => {
       returnUrl: "/chat",
       stage: "auth",
     });
-    await expect(NavigationStorage.peekPendingChatUnlock()).resolves.toMatchObject({
+    await expect(
+      NavigationStorage.peekPendingChatUnlock(CHARACTER_ID),
+    ).resolves.toMatchObject({
+      characterId: CHARACTER_ID,
       lockType: "image_paywall",
       clientLockId: promotion.clientLockId,
       promotion,
@@ -85,18 +106,62 @@ describe("NavigationStorage", () => {
 
   it("saves and consumes pending chat image return sessions", async () => {
     await NavigationStorage.savePendingChatImageReturn({
+      characterId: CHARACTER_ID,
       messageId: "msg_1",
       returnUrl: "/chat?image=msg_1",
     });
 
     await expect(
-      NavigationStorage.consumePendingChatImageReturn(),
+      NavigationStorage.consumePendingChatImageReturn(CHARACTER_ID),
     ).resolves.toMatchObject({
+      characterId: CHARACTER_ID,
       messageId: "msg_1",
       returnUrl: "/chat?image=msg_1",
     });
     await expect(
-      NavigationStorage.consumePendingChatImageReturn(),
+      NavigationStorage.consumePendingChatImageReturn(CHARACTER_ID),
     ).resolves.toBeNull();
   });
+
+  it("leaves another character's pending navigation state untouched", async () => {
+    const promotion = await NavigationStorage.savePendingChatPromotion(
+      "voice",
+      CHARACTER_ID,
+    );
+    await NavigationStorage.savePendingChatUnlock({
+      characterId: CHARACTER_ID,
+      displayMessageId: `promotion:${promotion.clientLockId}`,
+      kind: "voice",
+      lockType: promotion.lockType,
+      clientLockId: promotion.clientLockId,
+      promotion,
+      returnUrl: "/characters/elio/chat",
+      stage: "auth",
+    });
+    await NavigationStorage.savePendingChatImageReturn({
+      characterId: CHARACTER_ID,
+      messageId: "msg_1",
+      returnUrl: "/characters/elio/chat?image=msg_1",
+    });
+
+    await expect(
+      NavigationStorage.consumePendingChatPromotion(OTHER_CHARACTER_ID),
+    ).resolves.toBeNull();
+    await expect(
+      NavigationStorage.consumePendingChatUnlock(OTHER_CHARACTER_ID),
+    ).resolves.toBeNull();
+    await expect(
+      NavigationStorage.consumePendingChatImageReturn(OTHER_CHARACTER_ID),
+    ).resolves.toBeNull();
+
+    await expect(
+      NavigationStorage.consumePendingChatPromotion(CHARACTER_ID),
+    ).resolves.toEqual(promotion);
+    await expect(
+      NavigationStorage.consumePendingChatUnlock(CHARACTER_ID),
+    ).resolves.toMatchObject({ characterId: CHARACTER_ID });
+    await expect(
+      NavigationStorage.consumePendingChatImageReturn(CHARACTER_ID),
+    ).resolves.toMatchObject({ characterId: CHARACTER_ID });
+  });
 });

src/data/storage/navigation/navigation_storage.ts

@@ -14,6 +14,7 @@ export type PendingChatUnlockStage = "auth" | "payment";
 export type PendingChatPromotionType = "voice" | "image" | "private";
 
 export const PendingChatPromotionSchema = z.object({
+  characterId: z.string().min(1),
   promotionType: z.enum(["voice", "image", "private"]),
   lockType: ChatLockTypeSchema,
   clientLockId: z.string().min(1),
@@ -23,6 +24,7 @@ export const PendingChatPromotionSchema = z.object({
 const PendingChatUnlockSchema = z
   .object({
     reason: z.literal("single_message_unlock"),
+    characterId: z.string().min(1),
     displayMessageId: z.string().min(1),
     messageId: z.string().min(1).optional(),
     kind: z.enum(["private", "voice", "image"]),
@@ -45,6 +47,7 @@ const PendingChatUnlockSchema = z
 
 const PendingChatImageReturnSchema = z.object({
   reason: z.literal("image_paywall"),
+  characterId: z.string().min(1),
   messageId: z.string().min(1),
   returnUrl: z
     .string()
@@ -75,6 +78,7 @@ export class NavigationStorage {
   private constructor() {}
 
   static async savePendingChatUnlock(input: {
+    characterId: string;
     displayMessageId?: string;
     messageId?: string;
     kind: PendingChatUnlockKind;
@@ -91,8 +95,15 @@ export class NavigationStorage {
     if (!displayMessageId) {
       throw new Error("displayMessageId is required");
     }
+    if (
+      input.promotion &&
+      input.promotion.characterId !== input.characterId
+    ) {
+      throw new Error("Pending promotion belongs to a different character.");
+    }
     const payload: PendingChatUnlock = {
       reason: "single_message_unlock",
+      characterId: input.characterId,
       displayMessageId,
       ...(input.messageId ? { messageId: input.messageId } : {}),
       kind: input.kind,
@@ -110,31 +121,49 @@ export class NavigationStorage {
     );
   }
 
-  static async consumePendingChatUnlock(): Promise<PendingChatUnlock | null> {
+  static async consumePendingChatUnlock(
+    characterId: string,
+  ): Promise<PendingChatUnlock | null> {
     const result = await SessionAsyncUtil.getJson(
       StorageKeys.pendingChatUnlock,
       PendingChatUnlockSchema,
     );
+    if (Result.isErr(result)) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatUnlock);
+      return null;
+    }
+    const value = NavigationStorage.parsePendingChatUnlock(result.data);
+    if (!value) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatUnlock);
+      return null;
+    }
+    if (value.characterId !== characterId) return null;
     await SessionAsyncUtil.remove(StorageKeys.pendingChatUnlock);
-    if (Result.isErr(result)) return null;
+    return value;
-    return NavigationStorage.parsePendingChatUnlock(result.data);
   }
 
-  static async peekPendingChatUnlock(): Promise<PendingChatUnlock | null> {
+  static async peekPendingChatUnlock(
+    characterId: string,
+  ): Promise<PendingChatUnlock | null> {
     const result = await SessionAsyncUtil.getJson(
       StorageKeys.pendingChatUnlock,
       PendingChatUnlockSchema,
     );
-    if (Result.isErr(result)) return null;
+    if (Result.isErr(result)) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatUnlock);
+      return null;
+    }
     const value = NavigationStorage.parsePendingChatUnlock(result.data);
     if (!value) {
       await SessionAsyncUtil.remove(StorageKeys.pendingChatUnlock);
     }
-    return value;
+    return value?.characterId === characterId ? value : null;
   }
 
-  static async hasPendingChatUnlock(): Promise<boolean> {
+  static async hasPendingChatUnlock(characterId: string): Promise<boolean> {
-    return (await NavigationStorage.peekPendingChatUnlock()) !== null;
+    return (
+      (await NavigationStorage.peekPendingChatUnlock(characterId)) !== null
+    );
   }
 
   static async clearPendingChatUnlock(): Promise<void> {
@@ -143,8 +172,10 @@ export class NavigationStorage {
 
   static async savePendingChatPromotion(
     promotionType: PendingChatPromotionType,
+    characterId: string,
   ): Promise<PendingChatPromotion> {
     const promotion: PendingChatPromotion = {
+      characterId,
       promotionType,
       lockType: toPromotionLockType(promotionType),
       clientLockId: `promotion_${createUuidV4()}`,
@@ -158,14 +189,25 @@ export class NavigationStorage {
     return promotion;
   }
 
-  static async consumePendingChatPromotion(): Promise<PendingChatPromotion | null> {
+  static async consumePendingChatPromotion(
+    characterId: string,
+  ): Promise<PendingChatPromotion | null> {
     const result = await SessionAsyncUtil.getJson(
       StorageKeys.pendingChatPromotion,
       PendingChatPromotionSchema,
     );
+    if (Result.isErr(result)) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatPromotion);
+      return null;
+    }
+    const value = NavigationStorage.parsePendingChatPromotion(result.data);
+    if (!value) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatPromotion);
+      return null;
+    }
+    if (value.characterId !== characterId) return null;
     await SessionAsyncUtil.remove(StorageKeys.pendingChatPromotion);
-    if (Result.isErr(result)) return null;
+    return value;
-    return NavigationStorage.parsePendingChatPromotion(result.data);
   }
 
   static async clearPendingChatPromotion(): Promise<void> {
@@ -173,11 +215,13 @@ export class NavigationStorage {
   }
 
   static async savePendingChatImageReturn(input: {
+    characterId: string;
     messageId: string;
     returnUrl: string;
   }): Promise<void> {
     const payload: PendingChatImageReturn = {
       reason: "image_paywall",
+      characterId: input.characterId,
       messageId: input.messageId,
       returnUrl: input.returnUrl,
       createdAt: Date.now(),
@@ -189,14 +233,25 @@ export class NavigationStorage {
     );
   }
 
-  static async consumePendingChatImageReturn(): Promise<PendingChatImageReturn | null> {
+  static async consumePendingChatImageReturn(
+    characterId: string,
+  ): Promise<PendingChatImageReturn | null> {
     const result = await SessionAsyncUtil.getJson(
       StorageKeys.pendingChatImageReturn,
       PendingChatImageReturnSchema,
     );
+    if (Result.isErr(result)) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatImageReturn);
+      return null;
+    }
+    const value = NavigationStorage.parsePendingChatImageReturn(result.data);
+    if (!value) {
+      await SessionAsyncUtil.remove(StorageKeys.pendingChatImageReturn);
+      return null;
+    }
+    if (value.characterId !== characterId) return null;
     await SessionAsyncUtil.remove(StorageKeys.pendingChatImageReturn);
-    if (Result.isErr(result)) return null;
+    return value;
-    return NavigationStorage.parsePendingChatImageReturn(result.data);
   }
 
   private static parsePendingChatUnlock(

src/lib/chat/chat_cache_keys.ts

@@ -0,0 +1,29 @@
+import type { ChatMediaKind } from "@/data/schemas/chat";
+
+const CHARACTER_NAMESPACE = "::character:";
+const LEGACY_OWNER_KEY_PATTERN = /^(?:user|device):.+$/u;
+
+export function buildChatConversationKey(
+  ownerKey: string,
+  characterId: string,
+): string {
+  if (ownerKey.trim().length === 0 || characterId.trim().length === 0) {
+    throw new Error("Chat owner and character identities must not be empty.");
+  }
+  return `${ownerKey}${CHARACTER_NAMESPACE}${encodeURIComponent(characterId)}`;
+}
+
+export function buildChatMediaCacheKey(input: {
+  ownerKey: string;
+  messageId: string;
+  kind: ChatMediaKind;
+}): string {
+  return `${input.ownerKey}:${input.messageId}:${input.kind}`;
+}
+
+export function isLegacyChatCacheOwnerKey(ownerKey: string): boolean {
+  return (
+    !ownerKey.includes(CHARACTER_NAMESPACE) &&
+    LEGACY_OWNER_KEY_PATTERN.test(ownerKey)
+  );
+}

src/lib/navigation/__tests__/subscription_exit.test.ts

@@ -39,6 +39,7 @@ describe("subscription exit helpers", () => {
   it("uses explicit chat image return urls first", async () => {
     consumePendingChatImageReturnMock.mockResolvedValue({
       reason: "image_paywall",
+      characterId: "character_elio",
       messageId: "msg_1",
       returnUrl: "/chat?image=msg_1",
       createdAt: 1,
@@ -73,12 +74,14 @@ describe("subscription exit helpers", () => {
   it("returns directly to private room without consuming chat state", async () => {
     consumePendingChatImageReturnMock.mockResolvedValue({
       reason: "image_paywall",
+      characterId: "character_elio",
       messageId: "msg_1",
       returnUrl: "/chat?image=msg_1",
       createdAt: 1,
     });
     peekPendingChatUnlockMock.mockResolvedValue({
       reason: "single_message_unlock",
+      characterId: "character_elio",
       displayMessageId: "msg_1",
       messageId: "msg_1",
       kind: "image",
@@ -101,6 +104,7 @@ describe("subscription exit helpers", () => {
   it("keeps private room ahead of stale chat state after payment", async () => {
     peekPendingChatUnlockMock.mockResolvedValue({
       reason: "single_message_unlock",
+      characterId: "character_elio",
       displayMessageId: "msg_1",
       messageId: "msg_1",
       kind: "image",
@@ -119,6 +123,7 @@ describe("subscription exit helpers", () => {
   it("keeps pending chat unlocks ahead of chat fallback after payment", async () => {
     peekPendingChatUnlockMock.mockResolvedValue({
       reason: "single_message_unlock",
+      characterId: "character_elio",
       displayMessageId: "msg_1",
       messageId: "msg_1",
       kind: "image",
@@ -136,6 +141,7 @@ describe("subscription exit helpers", () => {
   it("peeks chat unlock return urls without clearing them", async () => {
     peekPendingChatUnlockMock.mockResolvedValue({
       reason: "single_message_unlock",
+      characterId: "character_elio",
       displayMessageId: "msg_1",
       messageId: "msg_1",
       kind: "image",
@@ -154,6 +160,7 @@ describe("subscription exit helpers", () => {
     consumePendingChatImageReturnMock.mockResolvedValue(null);
     peekPendingChatUnlockMock.mockResolvedValue({
       reason: "single_message_unlock",
+      characterId: "character_elio",
       displayMessageId: "msg_1",
       messageId: "msg_1",
       kind: "image",

src/lib/navigation/chat_image_return_session.ts

@@ -8,12 +8,15 @@ import {
 export type { PendingChatImageReturn };
 
 export async function savePendingChatImageReturn(input: {
+  characterId: string;
   messageId: string;
   returnUrl: string;
 }): Promise<void> {
   await NavigationStorage.savePendingChatImageReturn(input);
 }
 
-export async function consumePendingChatImageReturn(): Promise<PendingChatImageReturn | null> {
+export async function consumePendingChatImageReturn(
-  return NavigationStorage.consumePendingChatImageReturn();
+  characterId: string,
+): Promise<PendingChatImageReturn | null> {
+  return NavigationStorage.consumePendingChatImageReturn(characterId);
 }

src/lib/navigation/chat_unlock_session.ts

@@ -18,6 +18,7 @@ export type {
 };
 
 export async function savePendingChatUnlock(input: {
+  characterId: string;
   displayMessageId?: string;
   messageId?: string;
   kind: PendingChatUnlockKind;
@@ -30,16 +31,20 @@ export async function savePendingChatUnlock(input: {
   await NavigationStorage.savePendingChatUnlock(input);
 }
 
-export async function consumePendingChatUnlock(): Promise<PendingChatUnlock | null> {
+export async function consumePendingChatUnlock(
-  return NavigationStorage.consumePendingChatUnlock();
+  characterId: string,
+): Promise<PendingChatUnlock | null> {
+  return NavigationStorage.consumePendingChatUnlock(characterId);
 }
 
-export async function peekPendingChatUnlock(): Promise<PendingChatUnlock | null> {
+export async function peekPendingChatUnlock(
-  return NavigationStorage.peekPendingChatUnlock();
+  characterId: string,
+): Promise<PendingChatUnlock | null> {
+  return NavigationStorage.peekPendingChatUnlock(characterId);
 }
 
-export async function hasPendingChatUnlock(): Promise<boolean> {
+export async function hasPendingChatUnlock(characterId: string): Promise<boolean> {
-  return NavigationStorage.hasPendingChatUnlock();
+  return NavigationStorage.hasPendingChatUnlock(characterId);
 }
 
 export async function clearPendingChatUnlock(): Promise<void> {
@@ -48,12 +53,15 @@ export async function clearPendingChatUnlock(): Promise<void> {
 
 export async function savePendingChatPromotion(
   promotionType: PendingChatPromotionType,
+  characterId: string,
 ): Promise<PendingChatPromotion> {
-  return NavigationStorage.savePendingChatPromotion(promotionType);
+  return NavigationStorage.savePendingChatPromotion(promotionType, characterId);
 }
 
-export async function consumePendingChatPromotion(): Promise<PendingChatPromotion | null> {
+export async function consumePendingChatPromotion(
-  return NavigationStorage.consumePendingChatPromotion();
+  characterId: string,
+): Promise<PendingChatPromotion | null> {
+  return NavigationStorage.consumePendingChatPromotion(characterId);
 }
 
 export async function clearPendingChatPromotion(): Promise<void> {

src/lib/navigation/subscription_exit.ts

@@ -1,6 +1,10 @@
 "use client";
 
-import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER_ID,
+  DEFAULT_CHARACTER_SLUG,
+  getCharacterBySlug,
+} from "@/data/constants/character";
 import { getCharacterRoutes } from "@/router/routes";
 import type { AppSubscriptionReturnTo } from "@/router/navigation-types";
 
@@ -12,10 +16,13 @@ import {
 
 export type SubscriptionReturnTo = AppSubscriptionReturnTo;
 
-export async function consumeSubscriptionExplicitExitUrl(): Promise<string | null> {
+export async function consumeSubscriptionExplicitExitUrl(
-  const pendingImageReturn = await consumePendingChatImageReturn();
+  characterSlug: string = DEFAULT_CHARACTER_SLUG,
+): Promise<string | null> {
+  const characterId = resolveCharacterId(characterSlug);
+  const pendingImageReturn = await consumePendingChatImageReturn(characterId);
   if (pendingImageReturn) return pendingImageReturn.returnUrl;
-  const pendingChatUnlock = await peekPendingChatUnlock();
+  const pendingChatUnlock = await peekPendingChatUnlock(characterId);
   if (pendingChatUnlock) {
     await clearPendingChatUnlock();
     return pendingChatUnlock.returnUrl;
@@ -23,8 +30,12 @@ export async function consumeSubscriptionExplicitExitUrl(): Promise<string | nul
   return null;
 }
 
-export async function peekSubscriptionExplicitExitUrl(): Promise<string | null> {
+export async function peekSubscriptionExplicitExitUrl(
-  const pendingChatUnlock = await peekPendingChatUnlock();
+  characterSlug: string = DEFAULT_CHARACTER_SLUG,
+): Promise<string | null> {
+  const pendingChatUnlock = await peekPendingChatUnlock(
+    resolveCharacterId(characterSlug),
+  );
   if (pendingChatUnlock) return pendingChatUnlock.returnUrl;
   return null;
 }
@@ -48,7 +59,7 @@ export async function consumeSubscriptionExitUrl(
   }
 
   return (
-    (await consumeSubscriptionExplicitExitUrl()) ??
+    (await consumeSubscriptionExplicitExitUrl(characterSlug)) ??
     getSubscriptionFallbackExitUrl(returnTo, characterSlug)
   );
 }
@@ -61,7 +72,11 @@ export async function resolveSubscriptionSuccessExitUrl(
     return getCharacterRoutes(characterSlug).privateRoom;
   }
 
-  const pendingExitUrl = await peekSubscriptionExplicitExitUrl();
+  const pendingExitUrl = await peekSubscriptionExplicitExitUrl(characterSlug);
   if (pendingExitUrl) return pendingExitUrl;
   return consumeSubscriptionExitUrl(returnTo, characterSlug);
 }
+
+function resolveCharacterId(characterSlug: string): string {
+  return getCharacterBySlug(characterSlug)?.id ?? DEFAULT_CHARACTER_ID;
+}

src/providers/__tests__/character-actor-scope-providers.test.tsx

@@ -0,0 +1,189 @@
+/* @vitest-environment jsdom */
+
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const instances = vi.hoisted(() => ({
+  chat: 0,
+  payment: 0,
+  privateRoom: 0,
+}));
+
+vi.mock("@/stores/chat/chat-context", async () => {
+  const { createElement, useState } = await import("react");
+  return {
+    ChatProvider({
+      characterId,
+      children,
+    }: {
+      characterId: string;
+      children: ReactNode;
+    }) {
+      const [instanceId] = useState(() => ++instances.chat);
+      return createElement(
+        "div",
+        {
+          "data-character-id": characterId,
+          "data-instance-id": instanceId,
+          "data-testid": "chat-provider",
+        },
+        children,
+      );
+    },
+  };
+});
+
+vi.mock("@/stores/payment/payment-context", async () => {
+  const { createElement, useState } = await import("react");
+  return {
+    PaymentProvider({ children }: { children: ReactNode }) {
+      const [instanceId] = useState(() => ++instances.payment);
+      return createElement(
+        "div",
+        {
+          "data-instance-id": instanceId,
+          "data-testid": "payment-provider",
+        },
+        children,
+      );
+    },
+  };
+});
+
+vi.mock("@/stores/private-room", async () => {
+  const { createElement, useState } = await import("react");
+  return {
+    PrivateRoomProvider({
+      characterId,
+      children,
+    }: {
+      characterId: string;
+      children: ReactNode;
+    }) {
+      const [instanceId] = useState(() => ++instances.privateRoom);
+      return createElement(
+        "div",
+        {
+          "data-character-id": characterId,
+          "data-instance-id": instanceId,
+          "data-testid": "private-room-provider",
+        },
+        children,
+      );
+    },
+  };
+});
+
+vi.mock("@/stores/sync/chat-auth-sync", () => ({ ChatAuthSync: () => null }));
+vi.mock("@/stores/sync/chat-payment-success-sync", () => ({
+  ChatPaymentSuccessSync: () => null,
+}));
+vi.mock("@/stores/sync/payment-success-sync", () => ({
+  PaymentSuccessSync: () => null,
+}));
+
+import { ChatRouteProviders } from "@/providers/chat-route-providers";
+import { PaymentRouteProvider } from "@/providers/payment-route-provider";
+import { PrivateRoomRouteProvider } from "@/providers/private-room-route-provider";
+
+describe("character actor route providers", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    instances.chat = 0;
+    instances.payment = 0;
+    instances.privateRoom = 0;
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it("recreates chat and chat payment actors when the character changes", () => {
+    renderChat("character_elio");
+    const firstChatInstance = instanceId("chat-provider");
+    const firstPaymentInstance = instanceId("payment-provider");
+
+    renderChat("character_maya");
+
+    expect(instanceId("chat-provider")).not.toBe(firstChatInstance);
+    expect(instanceId("payment-provider")).not.toBe(firstPaymentInstance);
+    expect(testNode("chat-provider").dataset.characterId).toBe(
+      "character_maya",
+    );
+  });
+
+  it("recreates the private-room actor when the character changes", () => {
+    renderPrivateRoom("character_elio");
+    const firstInstance = instanceId("private-room-provider");
+
+    renderPrivateRoom("character_maya");
+
+    expect(instanceId("private-room-provider")).not.toBe(firstInstance);
+    expect(testNode("private-room-provider").dataset.characterId).toBe(
+      "character_maya",
+    );
+  });
+
+  it("recreates the route payment actor when its character scope changes", () => {
+    renderPayment("character_elio");
+    const firstInstance = instanceId("payment-provider");
+
+    renderPayment("character_maya");
+
+    expect(instanceId("payment-provider")).not.toBe(firstInstance);
+  });
+
+  function renderChat(characterId: string): void {
+    act(() => {
+      root.render(
+        <ChatRouteProviders
+          characterId={characterId}
+          emptyChatGreeting={`Hello from ${characterId}`}
+        >
+          <span>chat</span>
+        </ChatRouteProviders>,
+      );
+    });
+  }
+
+  function renderPrivateRoom(characterId: string): void {
+    act(() => {
+      root.render(
+        <PrivateRoomRouteProvider characterId={characterId}>
+          <span>private room</span>
+        </PrivateRoomRouteProvider>,
+      );
+    });
+  }
+
+  function renderPayment(scopeKey: string): void {
+    act(() => {
+      root.render(
+        <PaymentRouteProvider scopeKey={scopeKey}>
+          <span>payment</span>
+        </PaymentRouteProvider>,
+      );
+    });
+  }
+
+  function testNode(testId: string): HTMLElement {
+    const node = container.querySelector<HTMLElement>(
+      `[data-testid="${testId}"]`,
+    );
+    if (!node) throw new Error(`Missing ${testId}`);
+    return node;
+  }
+
+  function instanceId(testId: string): string | undefined {
+    return testNode(testId).dataset.instanceId;
+  }
+});

src/providers/__tests__/character-catalog-provider.test.tsx

@@ -0,0 +1,36 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { CHARACTERS } from "@/data/constants/character";
+import {
+  CharacterCatalogProvider,
+  useCharacterCatalog,
+} from "@/providers/character-catalog-provider";
+
+describe("CharacterCatalogProvider", () => {
+  it("provides the complete local character catalog", () => {
+    const html = renderToStaticMarkup(
+      <CharacterCatalogProvider>
+        <CatalogProbe />
+      </CharacterCatalogProvider>,
+    );
+
+    expect(html).toContain("elio,maya,nayeli");
+  });
+
+  it("accepts a serializable catalog snapshot", () => {
+    const html = renderToStaticMarkup(
+      <CharacterCatalogProvider characters={[CHARACTERS[1]]}>
+        <CatalogProbe />
+      </CharacterCatalogProvider>,
+    );
+
+    expect(html).toContain("maya");
+    expect(html).not.toContain("elio");
+  });
+});
+
+function CatalogProbe() {
+  const catalog = useCharacterCatalog();
+  return <span>{catalog.characters.map((character) => character.slug).join(",")}</span>;
+}

src/providers/character-catalog-provider.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useMemo,
+} from "react";
+
+import {
+  CHARACTERS,
+  createCharacterCatalog,
+  type CharacterCatalog,
+  type CharacterProfile,
+} from "@/data/constants/character";
+
+const CharacterCatalogContext = createContext<CharacterCatalog | null>(null);
+
+export interface CharacterCatalogProviderProps {
+  children: ReactNode;
+  characters?: readonly CharacterProfile[];
+}
+
+export function CharacterCatalogProvider({
+  children,
+  characters = CHARACTERS,
+}: CharacterCatalogProviderProps) {
+  const catalog = useMemo(
+    () => createCharacterCatalog(characters),
+    [characters],
+  );
+  return (
+    <CharacterCatalogContext.Provider value={catalog}>
+      {children}
+    </CharacterCatalogContext.Provider>
+  );
+}
+
+export function useCharacterCatalog(): CharacterCatalog {
+  const catalog = useContext(CharacterCatalogContext);
+  if (!catalog) {
+    throw new Error(
+      "useCharacterCatalog must be used within CharacterCatalogProvider.",
+    );
+  }
+  return catalog;
+}

src/providers/character-provider.tsx

@@ -2,13 +2,10 @@
 
 import { createContext, type ReactNode, useContext } from "react";
 
-import {
+import type { CharacterProfile } from "@/data/constants/character";
-  DEFAULT_CHARACTER,
-  type CharacterProfile,
-} from "@/data/constants/character";
 import { getCharacterRoutes, type CharacterRoutes } from "@/router/routes";
 
-const CharacterContext = createContext<CharacterProfile>(DEFAULT_CHARACTER);
+const CharacterContext = createContext<CharacterProfile | null>(null);
 
 export interface CharacterProviderProps {
   character: CharacterProfile;
@@ -27,7 +24,11 @@ export function CharacterProvider({
 }
 
 export function useActiveCharacter(): CharacterProfile {
-  return useContext(CharacterContext);
+  const character = useContext(CharacterContext);
+  if (!character) {
+    throw new Error("useActiveCharacter must be used within CharacterProvider.");
+  }
+  return character;
 }
 
 export function useActiveCharacterRoutes(): CharacterRoutes {

src/providers/chat-route-providers.tsx

@@ -2,7 +2,6 @@
 
 import type { ReactNode } from "react";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 import { ChatProvider } from "@/stores/chat/chat-context";
 import { PaymentProvider } from "@/stores/payment/payment-context";
 import { ChatAuthSync } from "@/stores/sync/chat-auth-sync";
@@ -11,17 +10,23 @@ import { PaymentSuccessSync } from "@/stores/sync/payment-success-sync";
 
 export interface ChatRouteProvidersProps {
   children: ReactNode;
-  characterId?: string;
+  characterId: string;
+  emptyChatGreeting: string;
 }
 
 export function ChatRouteProviders({
   children,
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
+  emptyChatGreeting,
 }: ChatRouteProvidersProps) {
   return (
-    <PaymentProvider>
+    <PaymentProvider key={characterId}>
       <PaymentSuccessSync />
-      <ChatProvider characterId={characterId}>
+      <ChatProvider
+        key={characterId}
+        characterId={characterId}
+        emptyChatGreeting={emptyChatGreeting}
+      >
         <ChatAuthSync />
         <ChatPaymentSuccessSync />
         {children}

src/providers/payment-route-provider.tsx

@@ -5,9 +5,17 @@ import type { ReactNode } from "react";
 import { PaymentProvider } from "@/stores/payment/payment-context";
 import { PaymentSuccessSync } from "@/stores/sync/payment-success-sync";
 
-export function PaymentRouteProvider({ children }: { children: ReactNode }) {
+export interface PaymentRouteProviderProps {
+  children: ReactNode;
+  scopeKey?: string;
+}
+
+export function PaymentRouteProvider({
+  children,
+  scopeKey,
+}: PaymentRouteProviderProps) {
   return (
-    <PaymentProvider>
+    <PaymentProvider key={scopeKey}>
       <PaymentSuccessSync />
       {children}
     </PaymentProvider>

src/providers/private-room-route-provider.tsx

@@ -2,20 +2,19 @@
 
 import type { ReactNode } from "react";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
 import { PrivateRoomProvider } from "@/stores/private-room";
 
 export interface PrivateRoomRouteProviderProps {
   children: ReactNode;
-  characterId?: string;
+  characterId: string;
 }
 
 export function PrivateRoomRouteProvider({
   children,
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
 }: PrivateRoomRouteProviderProps) {
   return (
-    <PrivateRoomProvider characterId={characterId}>
+    <PrivateRoomProvider key={characterId} characterId={characterId}>
       {children}
     </PrivateRoomProvider>
   );

src/providers/root-providers.tsx

@@ -3,12 +3,13 @@
 /**
  * 根级 Client Providers 包装
  *
- * 这里只保留跨路由的 Auth、User、消息预览和 viewport Provider。Chat、
+ * 这里只保留跨路由的 Character Catalog、Auth、User、消息预览和 viewport
- * Payment、PrivateRoom 状态机由对应路由 layout 按需挂载。
+ * Provider。Chat、Payment、PrivateRoom 状态机由对应路由 layout 按需挂载。
  */
 
 import type { ReactNode } from "react";
 
+import { CharacterCatalogProvider } from "@/providers/character-catalog-provider";
 import { SplashLatestMessageProvider } from "@/providers/splash-latest-message-provider";
 import { ViewportCssVarsProvider } from "@/providers/viewport-css-vars-provider";
 import { AppNavigationGuard } from "@/router/app-navigation-guard";
@@ -24,19 +25,21 @@ export interface RootProvidersProps {
 
 export function RootProviders({ children }: RootProvidersProps) {
   return (
-    <ViewportCssVarsProvider>
+    <CharacterCatalogProvider>
-      <AuthProvider>
+      <ViewportCssVarsProvider>
-        <AuthStatusChecker />
+        <AuthProvider>
-        <OAuthSessionSync />
+          <AuthStatusChecker />
-        <AppNavigationGuard />
+          <OAuthSessionSync />
-        <SplashLatestMessageProvider>
+          <AppNavigationGuard />
-          <UserProvider>
+          <SplashLatestMessageProvider>
-            <UserAuthSync />
+            <UserProvider>
-            {children}
+              <UserAuthSync />
-            <div id="toast-portal" />
+              {children}
-          </UserProvider>
+              <div id="toast-portal" />
-        </SplashLatestMessageProvider>
+            </UserProvider>
-      </AuthProvider>
+          </SplashLatestMessageProvider>
-    </ViewportCssVarsProvider>
+        </AuthProvider>
+      </ViewportCssVarsProvider>
+    </CharacterCatalogProvider>
   );
 }

src/router/use-app-navigator.ts

@@ -153,6 +153,7 @@ export function useAppNavigator(): AppNavigator {
 
       void (async () => {
         await NavigationStorage.savePendingChatUnlock({
+          characterId: character.id,
           displayMessageId,
           messageId,
           kind,
@@ -165,7 +166,7 @@ export function useAppNavigator(): AppNavigator {
         router.push(ROUTE_BUILDERS.authWithRedirect(returnUrl));
       })();
     },
-    [isAuthenticatedUser, router],
+    [character.id, isAuthenticatedUser, router],
   );
 
   const openSubscriptionForPendingUnlock = useCallback(
@@ -183,6 +184,7 @@ export function useAppNavigator(): AppNavigator {
     }: OpenSubscriptionForPendingUnlockInput): void => {
       void (async () => {
         await NavigationStorage.savePendingChatUnlock({
+          characterId: character.id,
           displayMessageId,
           messageId,
           kind,
@@ -200,7 +202,7 @@ export function useAppNavigator(): AppNavigator {
         });
       })();
     },
-    [getDefaultPayChannel, openSubscription],
+    [character.id, getDefaultPayChannel, openSubscription],
   );
 
   const exitSubscription = useCallback(

src/stores/chat/__tests__/chat-actor-cancellation.test.ts

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createActor } from "xstate";
+
+const repository = vi.hoisted(() => ({
+  prefetchMediaForSendResponse: vi.fn(async () => ({
+    success: true as const,
+    data: undefined,
+  })),
+  sendMessage: vi.fn(),
+  unlockHistory: vi.fn(),
+}));
+
+const historySync = vi.hoisted(() => ({
+  readAndSyncHistory: vi.fn(),
+  readLocalHistorySnapshot: vi.fn(async () => ({
+    messages: [],
+    localCount: 0,
+  })),
+  resolveHistoryCacheIdentity: vi.fn(async () => null),
+  syncNetworkHistory: vi.fn(),
+}));
+
+vi.mock("@/data/repositories/chat_repository_loader", () => ({
+  loadChatRepository: vi.fn(async () => repository),
+}));
+
+vi.mock("@/data/repositories/chat_cache_identity", () => ({
+  resolveChatConversationKey: vi.fn(async () => ({
+    success: true,
+    data: "user:test::character:character_elio",
+  })),
+}));
+
+vi.mock("@/stores/chat/chat-history-sync", () => historySync);
+
+import { loadHistoryActor } from "@/stores/chat/machine/actors/history";
+import { sendMessageHttpActor } from "@/stores/chat/machine/actors/send";
+import { unlockHistoryActor } from "@/stores/chat/machine/actors/unlock";
+
+describe("chat actor request cancellation", () => {
+  beforeEach(() => {
+    repository.sendMessage.mockReset();
+    repository.unlockHistory.mockReset();
+    historySync.syncNetworkHistory.mockReset();
+  });
+
+  it("aborts an in-flight send request when its actor stops", async () => {
+    repository.sendMessage.mockImplementation(() => new Promise(() => undefined));
+    const actor = createActor(sendMessageHttpActor, {
+      input: { characterId: "character_elio", content: "hello" },
+    }).start();
+    await vi.waitFor(() => expect(repository.sendMessage).toHaveBeenCalled());
+
+    const signal = getSignal(repository.sendMessage.mock.calls[0]?.[2]);
+    expect(signal.aborted).toBe(false);
+    actor.stop();
+    expect(signal.aborted).toBe(true);
+  });
+
+  it("aborts an in-flight history request when its callback actor stops", async () => {
+    historySync.syncNetworkHistory.mockImplementation(
+      () => new Promise(() => undefined),
+    );
+    const actor = createActor(loadHistoryActor, {
+      input: {
+        characterId: "character_elio",
+        emptyChatGreeting: "Hello from Elio",
+      },
+    }).start();
+    await vi.waitFor(() =>
+      expect(historySync.syncNetworkHistory).toHaveBeenCalled(),
+    );
+
+    const historyCall = historySync.syncNetworkHistory.mock.calls[0];
+    expect(historyCall?.[3]).toBe("Hello from Elio");
+    const signal = getSignal(historyCall?.[4]);
+    expect(signal.aborted).toBe(false);
+    actor.stop();
+    expect(signal.aborted).toBe(true);
+  });
+
+  it("aborts an in-flight unlock request when its actor stops", async () => {
+    repository.unlockHistory.mockImplementation(
+      () => new Promise(() => undefined),
+    );
+    const actor = createActor(unlockHistoryActor, {
+      input: {
+        characterId: "character_elio",
+        emptyChatGreeting: "Hello from Elio",
+      },
+    }).start();
+    await vi.waitFor(() => expect(repository.unlockHistory).toHaveBeenCalled());
+
+    const signal = getSignal(repository.unlockHistory.mock.calls[0]?.[1]);
+    expect(signal.aborted).toBe(false);
+    actor.stop();
+    expect(signal.aborted).toBe(true);
+  });
+});
+
+function getSignal(options: unknown): AbortSignal {
+  if (options instanceof AbortSignal) return options;
+  const signal = (options as { signal?: AbortSignal } | undefined)?.signal;
+  if (!signal) throw new Error("Missing AbortSignal");
+  return signal;
+}

src/stores/chat/__tests__/chat-helpers.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER,
+  DEFAULT_CHARACTER_ID,
+} from "@/data/constants/character";
 import {
   ChatSendResponseSchema,
   type ChatSendResponse,
@@ -35,6 +38,7 @@ function makeResponse(
 function makeChatState(overrides: Partial<ChatState> = {}): ChatState {
   return {
     characterId: DEFAULT_CHARACTER_ID,
+    emptyChatGreeting: DEFAULT_CHARACTER.emptyChatGreeting,
     messages: [],
     promotion: null,
     outgoingMessageRevision: 0,

src/stores/chat/__tests__/chat-history-flow.test.ts

@@ -4,7 +4,10 @@ import { createActor, fromCallback, waitFor } from "xstate";
 import type { UiMessage } from "@/stores/chat/ui-message";
 import type { ChatEvent } from "@/stores/chat/chat-events";
 import { chatMachine } from "@/stores/chat/chat-machine";
-import type { LoadMoreHistoryActorEvent } from "@/stores/chat/machine/actors/history";
+import type {
+  ChatHistoryActorInput,
+  LoadMoreHistoryActorEvent,
+} from "@/stores/chat/machine/actors/history";
 
 import {
   createLoadHistoryCallback,
@@ -50,7 +53,7 @@ describe("chat history flow", () => {
       actors: {
         loadHistory: fromCallback<
           ChatEvent,
-          { characterId: string }
+          ChatHistoryActorInput
         >(({ sendBack }) => {
           sendBack({
             type: "ChatLocalHistoryLoaded",
@@ -119,7 +122,7 @@ describe("chat history flow", () => {
         ),
         loadMoreHistory: fromCallback<
           LoadMoreHistoryActorEvent,
-          { characterId: string }
+          ChatHistoryActorInput
         >(
           ({ receive, sendBack }) => {
             receive((event) => {
@@ -198,7 +201,7 @@ describe("chat history flow", () => {
         }),
         loadMoreHistory: fromCallback<
           LoadMoreHistoryActorEvent,
-          { characterId: string }
+          ChatHistoryActorInput
         >(
           ({ receive, sendBack }) => {
             receive((event) => {
@@ -260,7 +263,7 @@ describe("chat history flow", () => {
         }),
         loadMoreHistory: fromCallback<
           LoadMoreHistoryActorEvent,
-          { characterId: string }
+          ChatHistoryActorInput
         >(
           ({ receive }) => {
             receive(() => {

src/stores/chat/__tests__/chat-machine.test-utils.ts

@@ -1,6 +1,9 @@
 import { fromCallback, fromPromise } from "xstate";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER,
+  DEFAULT_CHARACTER_ID,
+} from "@/data/constants/character";
 import {
   ChatSendResponseSchema,
   UnlockPrivateResponseSchema,
@@ -36,6 +39,7 @@ export interface TestUnlockMessageOutput {
 
 export const TEST_CHAT_MACHINE_INPUT = {
   characterId: DEFAULT_CHARACTER_ID,
+  emptyChatGreeting: DEFAULT_CHARACTER.emptyChatGreeting,
 };
 
 export function makeChatSendResponse(): ChatSendResponse {
@@ -109,7 +113,10 @@ export function createTestChatMachine(
           return () => undefined;
         },
       ),
-      unlockHistory: fromPromise<UnlockHistoryOutput, { characterId: string }>(
+      unlockHistory: fromPromise<
+        UnlockHistoryOutput,
+        { characterId: string; emptyChatGreeting: string }
+      >(
         async () => {
           if (options.unlockHistoryError) {
             throw options.unlockHistoryError;

src/stores/chat/__tests__/chat-promotion.test.ts

@@ -9,6 +9,7 @@ import {
 } from "@/stores/chat/helper/promotion";
 
 const promotion: PendingChatPromotion = {
+  characterId: "character_elio",
   promotionType: "image",
   lockType: "image_paywall",
   clientLockId: "promotion-1",

src/stores/chat/__tests__/chat-send-flow.test.ts

@@ -155,7 +155,7 @@ describe("chat send flow", () => {
         ),
         unlockHistory: fromPromise<
           UnlockHistoryOutput,
-          { characterId: string }
+          { characterId: string; emptyChatGreeting: string }
         >(async () => ({
           unlocked: true,
           reason: "ok",

src/stores/chat/__tests__/chat-session-flow.test.ts

@@ -9,10 +9,43 @@ import {
 describe("chat session flow", () => {
   it("initializes the conversation from the supplied character", () => {
     const actor = createActor(createTestChatMachine(), {
-      input: { characterId: "character_aria" },
+      input: {
+        characterId: "character_maya",
+        emptyChatGreeting: "Hello from Maya",
+      },
     }).start();
 
-    expect(actor.getSnapshot().context.characterId).toBe("character_aria");
+    expect(actor.getSnapshot().context).toMatchObject({
+      characterId: "character_maya",
+      emptyChatGreeting: "Hello from Maya",
+    });
+    actor.stop();
+  });
+
+  it("keeps the active character greeting across login state changes", async () => {
+    const actor = createActor(createTestChatMachine(), {
+      input: {
+        characterId: "character_maya",
+        emptyChatGreeting: "Hello from Maya",
+      },
+    }).start();
+
+    actor.send({ type: "ChatUserLogin", token: "token" });
+    await waitFor(actor, (snapshot) =>
+      snapshot.matches({ userSession: "ready" }),
+    );
+    expect(actor.getSnapshot().context.emptyChatGreeting).toBe(
+      "Hello from Maya",
+    );
+
+    actor.send({ type: "ChatGuestLogin" });
+    await waitFor(actor, (snapshot) =>
+      snapshot.matches({ guestSession: "ready" }),
+    );
+    expect(actor.getSnapshot().context.emptyChatGreeting).toBe(
+      "Hello from Maya",
+    );
+
     actor.stop();
   });
 
@@ -80,6 +113,7 @@ describe("chat session flow", () => {
     actor.send({
       type: "ChatPromotionInjected",
       promotion: {
+        characterId: "character_elio",
         promotionType: "voice",
         lockType: "voice_message",
         clientLockId: "promotion-1",

src/stores/chat/chat-context.tsx

@@ -4,8 +4,6 @@ import { type Dispatch, type ReactNode, useMemo } from "react";
 import { createActorContext, shallowEqual } from "@xstate/react";
 import type { SnapshotFrom } from "xstate";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
-
 import { chatMachine } from "./chat-machine";
 import type { ChatEvent, ChatState as MachineContext } from "./chat-machine";
 import { appendPromotionMessage } from "./helper/promotion";
@@ -46,15 +44,19 @@ const ChatActorContext = createActorContext(chatMachine);
 
 export interface ChatProviderProps {
   children: ReactNode;
-  characterId?: string;
+  characterId: string;
+  emptyChatGreeting: string;
 }
 
 export function ChatProvider({
   children,
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
+  emptyChatGreeting,
 }: ChatProviderProps) {
   return (
-    <ChatActorContext.Provider options={{ input: { characterId } }}>
+    <ChatActorContext.Provider
+      options={{ input: { characterId, emptyChatGreeting } }}
+    >
       {children}
     </ChatActorContext.Provider>
   );

src/stores/chat/chat-history-sync.ts

@@ -4,6 +4,7 @@ import { loadChatRepository } from "@/data/repositories/chat_repository_loader";
 import { Logger } from "@/utils/logger";
 import { Result } from "@/utils/result";
 import { todayString } from "@/utils/date";
+import { isAbortError } from "@/utils/abort";
 
 import { CHAT_HISTORY_LIMIT } from "./helper/history";
 import { localMessagesToUi } from "./helper/message-mappers";
@@ -29,12 +30,9 @@ export type LocalHistorySnapshotOutput = {
 
 export type NetworkHistorySyncOutput = ReadAndSyncHistoryOutput;
 
-export function createGreetingMessage(): UiMessage {
+export function createGreetingMessage(content: string): UiMessage {
   return {
-    content:
+    content,
-      "You're here! Facebook is so restrictive, " +
-      "there were things I couldn't say there. " +
-      "Finally I can relax. How was your day out?",
     isFromAI: true,
     date: todayString(),
     isSynthetic: true,
@@ -50,9 +48,10 @@ export async function resolveHistoryCacheIdentity(
 
 export async function readLocalHistorySnapshot(
   cacheIdentity: string | null,
+  emptyChatGreeting: string,
 ): Promise<LocalHistorySnapshotOutput> {
   const chatRepo = await loadChatRepository();
-  const greetingMessage = createGreetingMessage();
+  const greetingMessage = createGreetingMessage(emptyChatGreeting);
 
   const localResult = cacheIdentity
     ? await chatRepo.getLocalMessages(cacheIdentity)
@@ -81,21 +80,26 @@ export async function syncNetworkHistory(
   characterId: string,
   localCount: number,
   cacheIdentity: string | null,
+  emptyChatGreeting: string,
+  signal?: AbortSignal,
 ): Promise<NetworkHistorySyncOutput | null> {
   const chatRepo = await loadChatRepository();
-  const greetingMessage = createGreetingMessage();
+  const greetingMessage = createGreetingMessage(emptyChatGreeting);
 
   const networkResult = await chatRepo.getHistory(
     characterId,
     CHAT_HISTORY_LIMIT,
     0,
+    { signal },
   );
   if (Result.isErr(networkResult)) {
+    if (isAbortError(networkResult.error)) throw networkResult.error;
     log.error("[chat-machine] loadHistory NETWORK FAILED", {
       error: networkResult.error,
     });
     return null;
   }
+  signal?.throwIfAborted();
 
   const networkUi = localMessagesToUi(networkResult.data.messages);
   log.debug("[chat-machine] loadHistory NETWORK DONE", {
@@ -144,13 +148,20 @@ export async function syncNetworkHistory(
  */
 export async function readAndSyncHistory(
   characterId: string,
+  emptyChatGreeting: string,
+  signal?: AbortSignal,
 ): Promise<ReadAndSyncHistoryOutput> {
   const cacheIdentity = await resolveHistoryCacheIdentity(characterId);
-  const localSnapshot = await readLocalHistorySnapshot(cacheIdentity);
+  const localSnapshot = await readLocalHistorySnapshot(
+    cacheIdentity,
+    emptyChatGreeting,
+  );
   const networkSnapshot = await syncNetworkHistory(
     characterId,
     localSnapshot.localCount,
     cacheIdentity,
+    emptyChatGreeting,
+    signal,
   );
   if (networkSnapshot) return networkSnapshot;
 

src/stores/chat/chat-machine.ts

@@ -2,7 +2,10 @@ import {
   chatMachineSetup,
   chatRootStateConfig,
 } from "./machine/session-flow";
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER,
+  DEFAULT_CHARACTER_ID,
+} from "@/data/constants/character";
 
 import { createInitialChatState } from "./chat-state";
 
@@ -13,7 +16,10 @@ export type { ChatEvent } from "./chat-events";
 export const chatMachine = chatMachineSetup.createMachine({
   id: "chat",
   context: ({ input }) =>
-    createInitialChatState(input?.characterId ?? DEFAULT_CHARACTER_ID),
+    createInitialChatState(
+      input?.characterId ?? DEFAULT_CHARACTER_ID,
+      input?.emptyChatGreeting ?? DEFAULT_CHARACTER.emptyChatGreeting,
+    ),
   ...chatRootStateConfig,
 });
 

src/stores/chat/chat-state.ts

@@ -2,7 +2,10 @@ import type { UiMessage } from "@/stores/chat/ui-message";
 import type { PendingChatUnlockKind } from "@/lib/navigation/chat_unlock_session";
 import type { ChatLockType } from "@/data/schemas/chat";
 import type { PendingChatPromotion } from "@/data/storage/navigation";
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER,
+  DEFAULT_CHARACTER_ID,
+} from "@/data/constants/character";
 import type { ChatPromotionState } from "./helper/promotion";
 
 export type ChatUpgradeReason = "insufficient_credits";
@@ -26,6 +29,7 @@ export interface ChatUnlockPaywallRequest
 
 export interface ChatState {
   characterId: string;
+  emptyChatGreeting: string;
   messages: UiMessage[];
   promotion: ChatPromotionState | null;
   outgoingMessageRevision: number;
@@ -55,9 +59,11 @@ export interface ChatState {
 
 export function createInitialChatState(
   characterId: string = DEFAULT_CHARACTER_ID,
+  emptyChatGreeting: string = DEFAULT_CHARACTER.emptyChatGreeting,
 ): ChatState {
   return {
     characterId,
+    emptyChatGreeting,
     messages: [],
     promotion: null,
     outgoingMessageRevision: 0,

src/stores/chat/machine/actors/history.ts

@@ -4,6 +4,7 @@ import type { UiMessage } from "@/stores/chat/ui-message";
 import { loadChatRepository } from "@/data/repositories/chat_repository_loader";
 import { Logger } from "@/utils/logger";
 import { Result } from "@/utils/result";
+import { isAbortError } from "@/utils/abort";
 
 import {
   readLocalHistorySnapshot,
@@ -24,6 +25,7 @@ export interface LoadMoreHistoryActorEvent {
 
 export interface ChatHistoryActorInput {
   characterId: string;
+  emptyChatGreeting: string;
 }
 
 export interface LoadMoreHistoryOutput {
@@ -38,10 +40,14 @@ export const loadHistoryActor = fromCallback<
   ChatHistoryActorInput
 >(({ input, sendBack }) => {
   let cancelled = false;
+  const controller = new AbortController();
 
   void (async () => {
     const cacheIdentity = await resolveHistoryCacheIdentity(input.characterId);
-    const localSnapshot = await readLocalHistorySnapshot(cacheIdentity);
+    const localSnapshot = await readLocalHistorySnapshot(
+      cacheIdentity,
+      input.emptyChatGreeting,
+    );
     if (cancelled) return;
     sendBack({
       type: "ChatLocalHistoryLoaded",
@@ -52,6 +58,8 @@ export const loadHistoryActor = fromCallback<
       input.characterId,
       localSnapshot.localCount,
       cacheIdentity,
+      input.emptyChatGreeting,
+      controller.signal,
     );
     if (cancelled || !networkSnapshot) return;
     sendBack({
@@ -59,13 +67,14 @@ export const loadHistoryActor = fromCallback<
       output: networkSnapshot,
     });
   })().catch((error: unknown) => {
-    if (cancelled) return;
+    if (cancelled || isAbortError(error)) return;
     log.error("[chat-machine] loadHistoryActor failed", { error });
     sendBack({ type: "ChatHistoryLoadFailed", error });
   });
 
   return () => {
     cancelled = true;
+    controller.abort();
   };
 });
 
@@ -74,10 +83,13 @@ export const loadMoreHistoryActor =
     ({ input, receive, sendBack }) => {
       let cancelled = false;
       let running = false;
+      let activeController: AbortController | null = null;
 
       receive((event) => {
         if (running || cancelled) return;
         running = true;
+        const controller = new AbortController();
+        activeController = controller;
 
         void (async () => {
           const chatRepo = await loadChatRepository();
@@ -85,6 +97,7 @@ export const loadMoreHistoryActor =
             input.characterId,
             event.limit,
             event.offset,
+            { signal: controller.signal },
           );
           if (Result.isErr(historyResult)) throw historyResult.error;
           if (cancelled) return;
@@ -111,17 +124,19 @@ export const loadMoreHistoryActor =
           );
         })()
           .catch((error: unknown) => {
-            if (cancelled) return;
+            if (cancelled || isAbortError(error)) return;
             log.warn("[chat-machine] loadMoreHistoryActor failed", { error });
             sendBack({ type: "ChatOlderHistoryLoadFailed", error });
           })
           .finally(() => {
+            if (activeController === controller) activeController = null;
             running = false;
           });
       });
 
       return () => {
         cancelled = true;
+        activeController?.abort();
       };
     },
   );

src/stores/chat/machine/actors/send.ts

@@ -7,6 +7,7 @@ import { loadChatRepository } from "@/data/repositories/chat_repository_loader";
 import { resolveChatConversationKey } from "@/data/repositories/chat_cache_identity";
 import { Logger } from "@/utils/logger";
 import { Result } from "@/utils/result";
+import { isAbortError } from "@/utils/abort";
 
 import type { ChatEvent } from "../../chat-events";
 import { sendResponseToUiMessage } from "../../helper/message-mappers";
@@ -18,8 +19,8 @@ type UiMessage = import("@/stores/chat/ui-message").UiMessage;
 export const sendMessageHttpActor = fromPromise<
   { response: ChatSendResponse; reply: UiMessage | null },
   { characterId: string; content: string }
->(async ({ input }) => {
+>(async ({ input, signal }) => {
-  return sendMessageViaHttp(input.characterId, input.content);
+  return sendMessageViaHttp(input.characterId, input.content, signal);
 });
 
 export const httpMessageQueueActor = fromCallback<
@@ -37,13 +38,21 @@ function createMessageQueueActor(
   receive: (listener: (event: ChatEvent) => void) => void,
 ): () => void {
   const queue = new MessageQueue();
+  let activeController: AbortController | null = null;
 
   queue.setConsumer(async (content) => {
+    const controller = new AbortController();
+    activeController = controller;
     sendBack({ type: "ChatQueuedSendStarted" });
     try {
-      const output = await sendMessageViaHttp(characterId, content);
+      const output = await sendMessageViaHttp(
+        characterId,
+        content,
+        controller.signal,
+      );
       sendBack({ type: "ChatQueuedHttpDone", output });
     } catch (error) {
+      if (isAbortError(error)) return;
       const errorMessage = ExceptionHandler.message(error);
       log.error("[chat-machine] message queue send failed", {
         error,
@@ -53,6 +62,8 @@ function createMessageQueueActor(
         content,
         errorMessage,
       });
+    } finally {
+      if (activeController === controller) activeController = null;
     }
   });
 
@@ -63,22 +74,31 @@ function createMessageQueueActor(
     queue.enqueue(content);
   });
 
-  return () => queue.dispose();
+  return () => {
+    activeController?.abort();
+    queue.dispose();
+  };
 }
 
-async function sendMessageViaHttp(characterId: string, content: string): Promise<{
+async function sendMessageViaHttp(
+  characterId: string,
+  content: string,
+  signal?: AbortSignal,
+): Promise<{
   response: ChatSendResponse;
   reply: UiMessage | null;
 }> {
   const chatRepo = await loadChatRepository();
   const cacheIdentityResult = await resolveChatConversationKey(characterId);
-  const result = await chatRepo.sendMessage(characterId, content);
+  const result = await chatRepo.sendMessage(characterId, content, { signal });
   if (Result.isErr(result)) {
+    if (isAbortError(result.error)) throw result.error;
     log.error("[chat-machine] sendMessageHttpActor failed", {
       error: result.error,
     });
     throw result.error;
   }
+  signal?.throwIfAborted();
   if (Result.isOk(cacheIdentityResult)) {
     void chatRepo.prefetchMediaForSendResponse(
       result.data,

src/stores/chat/machine/actors/unlock.ts

@@ -4,6 +4,7 @@ import { loadChatRepository } from "@/data/repositories/chat_repository_loader";
 import { resolveChatConversationKey } from "@/data/repositories/chat_cache_identity";
 import { Logger } from "@/utils/logger";
 import { Result } from "@/utils/result";
+import { isAbortError } from "@/utils/abort";
 
 import { readAndSyncHistory } from "../../chat-history-sync";
 import {
@@ -24,18 +25,26 @@ export interface UnlockHistoryOutput {
 
 export const unlockHistoryActor = fromPromise<
   UnlockHistoryOutput,
-  { characterId: string }
+  { characterId: string; emptyChatGreeting: string }
->(async ({ input }) => {
+>(async ({ input, signal }) => {
   const chatRepo = await loadChatRepository();
-  const unlockResult = await chatRepo.unlockHistory(input.characterId);
+  const unlockResult = await chatRepo.unlockHistory(input.characterId, {
+    signal,
+  });
   if (Result.isErr(unlockResult)) {
+    if (isAbortError(unlockResult.error)) throw unlockResult.error;
     log.error("[chat-machine] unlockHistoryActor failed", {
       error: unlockResult.error,
     });
     throw unlockResult.error;
   }
 
-  const history = await readAndSyncHistory(input.characterId);
+  signal.throwIfAborted();
+  const history = await readAndSyncHistory(
+    input.characterId,
+    input.emptyChatGreeting,
+    signal,
+  );
   return {
     unlocked: unlockResult.data.unlocked,
     reason: unlockResult.data.reason,
@@ -47,18 +56,22 @@ export const unlockHistoryActor = fromPromise<
 export const unlockMessageActor = fromPromise<
   UnlockMessageOutput,
   UnlockMessageRequest & { characterId: string }
->(async ({ input }) => {
+>(async ({ input, signal }) => {
   const chatRepo = await loadChatRepository();
   const cacheIdentityResult = await resolveChatConversationKey(
     input.characterId,
   );
-  const unlockResult = await chatRepo.unlockPrivateMessage({
+  const unlockResult = await chatRepo.unlockPrivateMessage(
-    characterId: input.characterId,
+    {
-    ...(input.messageId ? { messageId: input.messageId } : {}),
+      characterId: input.characterId,
-    ...(input.lockType ? { lockType: input.lockType } : {}),
+      ...(input.messageId ? { messageId: input.messageId } : {}),
-    ...(input.clientLockId ? { clientLockId: input.clientLockId } : {}),
+      ...(input.lockType ? { lockType: input.lockType } : {}),
-  });
+      ...(input.clientLockId ? { clientLockId: input.clientLockId } : {}),
+    },
+    { signal },
+  );
   if (Result.isErr(unlockResult)) {
+    if (isAbortError(unlockResult.error)) throw unlockResult.error;
     log.error("[chat-machine] unlockMessageActor failed", {
       messageId: input.messageId,
       clientLockId: input.clientLockId,
@@ -66,6 +79,7 @@ export const unlockMessageActor = fromPromise<
     });
     throw unlockResult.error;
   }
+  signal.throwIfAborted();
 
   if (
     unlockResult.data.unlocked &&

src/stores/chat/machine/session-flow.ts

@@ -19,20 +19,26 @@ import {
 
 const startGuestSessionAction = unlockMachineSetup.assign(
   ({ context }) => ({
-    ...createInitialChatState(context.characterId),
+    ...createInitialChatState(
+      context.characterId,
+      context.emptyChatGreeting,
+    ),
     promotion: context.promotion,
   }),
 );
 
 const startUserSessionAction = unlockMachineSetup.assign(
   ({ context }) => ({
-    ...createInitialChatState(context.characterId),
+    ...createInitialChatState(
+      context.characterId,
+      context.emptyChatGreeting,
+    ),
     promotion: context.promotion,
   }),
 );
 
 const clearChatSessionAction = unlockMachineSetup.assign(({ context }) => ({
-  ...createInitialChatState(context.characterId),
+  ...createInitialChatState(context.characterId, context.emptyChatGreeting),
 }));
 
 const injectPromotionAction = unlockMachineSetup.assign(({ event }) => {
@@ -80,12 +86,18 @@ const guestSessionState = chatMachineSetup.createStateConfig({
     {
       id: "loadHistory",
       src: "loadHistory",
-      input: ({ context }) => ({ characterId: context.characterId }),
+      input: ({ context }) => ({
+        characterId: context.characterId,
+        emptyChatGreeting: context.emptyChatGreeting,
+      }),
     },
     {
       id: "loadMoreHistory",
       src: "loadMoreHistory",
-      input: ({ context }) => ({ characterId: context.characterId }),
+      input: ({ context }) => ({
+        characterId: context.characterId,
+        emptyChatGreeting: context.emptyChatGreeting,
+      }),
     },
   ],
   on: {
@@ -162,12 +174,18 @@ const userSessionState = chatMachineSetup.createStateConfig({
     {
       id: "loadHistory",
       src: "loadHistory",
-      input: ({ context }) => ({ characterId: context.characterId }),
+      input: ({ context }) => ({
+        characterId: context.characterId,
+        emptyChatGreeting: context.emptyChatGreeting,
+      }),
     },
     {
       id: "loadMoreHistory",
       src: "loadMoreHistory",
-      input: ({ context }) => ({ characterId: context.characterId }),
+      input: ({ context }) => ({
+        characterId: context.characterId,
+        emptyChatGreeting: context.emptyChatGreeting,
+      }),
     },
   ],
   on: {

src/stores/chat/machine/setup.ts

@@ -17,6 +17,7 @@ import type { ChatState } from "../chat-state";
 
 export interface ChatMachineInput {
   characterId?: string;
+  emptyChatGreeting?: string;
 }
 
 export const baseChatMachineSetup = setup({

src/stores/chat/machine/unlock-flow.ts

@@ -188,7 +188,10 @@ export const unlockingHistoryState = unlockMachineSetup.createStateConfig({
   invoke: {
     id: "unlockHistory",
     src: "unlockHistory",
-    input: ({ context }) => ({ characterId: context.characterId }),
+    input: ({ context }) => ({
+      characterId: context.characterId,
+      emptyChatGreeting: context.emptyChatGreeting,
+    }),
     onDone: {
       target: "ready",
       actions: applyUnlockHistoryOutputAction,

src/stores/private-room/private-room-context.tsx

@@ -4,8 +4,6 @@ import type { Dispatch, ReactNode } from "react";
 import { createActorContext, shallowEqual } from "@xstate/react";
 import type { SnapshotFrom } from "xstate";
 
-import { DEFAULT_CHARACTER_ID } from "@/data/constants/character";
-
 import { privateRoomMachine } from "./private-room-machine";
 import type {
   PrivateRoomEvent,
@@ -34,12 +32,12 @@ const PrivateRoomActorContext = createActorContext(privateRoomMachine);
 
 export interface PrivateRoomProviderProps {
   children: ReactNode;
-  characterId?: string;
+  characterId: string;
 }
 
 export function PrivateRoomProvider({
   children,
-  characterId = DEFAULT_CHARACTER_ID,
+  characterId,
 }: PrivateRoomProviderProps) {
   return (
     <PrivateRoomActorContext.Provider options={{ input: { characterId } }}>

src/stores/sync/chat-payment-success-sync.tsx

@@ -5,7 +5,10 @@ import { useEffect, useRef } from "react";
 import { shallowEqual } from "@xstate/react";
 
 import { hasPendingChatUnlock } from "@/lib/navigation/chat_unlock_session";
-import { useChatDispatch } from "@/stores/chat/chat-context";
+import {
+  useChatDispatch,
+  useChatSelector,
+} from "@/stores/chat/chat-context";
 import { usePaymentSelector } from "@/stores/payment/payment-context";
 
 export function ChatPaymentSuccessSync() {
@@ -17,6 +20,7 @@ export function ChatPaymentSuccessSync() {
     }),
     shallowEqual,
   );
+  const characterId = useChatSelector((state) => state.context.characterId);
   const chatDispatch = useChatDispatch();
   const lastPaidKeyRef = useRef<string | null>(null);
 
@@ -29,7 +33,7 @@ export function ChatPaymentSuccessSync() {
 
     let cancelled = false;
     void (async () => {
-      if (await hasPendingChatUnlock()) return;
+      if (await hasPendingChatUnlock(characterId)) return;
       if (!cancelled) chatDispatch({ type: "ChatPaymentSucceeded" });
     })();
 
@@ -38,6 +42,7 @@ export function ChatPaymentSuccessSync() {
     };
   }, [
     chatDispatch,
+    characterId,
     paymentState.currentOrderId,
     paymentState.isPaid,
     paymentState.orderStatus,

src/utils/__tests__/abort.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { isAbortError } from "@/utils/abort";
+import { Result } from "@/utils/result";
+
+describe("isAbortError", () => {
+  it("recognizes cancellation after Result normalizes the error", async () => {
+    const result = await Result.wrap(async () => {
+      throw new DOMException("This operation was aborted", "AbortError");
+    });
+
+    expect(Result.isErr(result) && isAbortError(result.error)).toBe(true);
+  });
+
+  it("does not treat request timeouts as actor cancellation", () => {
+    expect(isAbortError(new DOMException("Timed out", "TimeoutError"))).toBe(
+      false,
+    );
+  });
+});

src/utils/abort.ts

@@ -0,0 +1,6 @@
+export function isAbortError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === "AbortError") return true;
+  const cause = error.cause;
+  return cause !== error && isAbortError(cause);
+}