test(e2e): align simplified splash expectations

Dockerfile

@@ -6,10 +6,12 @@ ENV PNPM_HOME=/pnpm
 ENV PNPM_STORE_PATH=/pnpm/store
 ENV PATH=$PNPM_HOME:$PATH
 
+ARG NPM_REGISTRY=https://registry.npmmirror.com
+
 RUN apk add --no-cache libc6-compat \
-  && corepack enable \
+  && npm install --global "pnpm@10.30.3" --registry="$NPM_REGISTRY" \
-  && corepack prepare pnpm@10.30.3 --activate \
+  && pnpm config set store-dir "$PNPM_STORE_PATH" \
-  && pnpm config set store-dir "$PNPM_STORE_PATH"
+  && pnpm config set registry "$NPM_REGISTRY"
 
 FROM base AS deps
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./

e2e/fixtures/api/chat.ts

@@ -20,6 +20,23 @@ export interface ChatMockState {
 export async function registerChatMocks(page: Page, options: ChatMockOptions, state: ChatMockState) {
   let sendCount = 0;
 
+  await page.route("**/api/chat/opening-message", async (route) => {
+    const body = route.request().postDataJSON() as {
+      openingMessage?: unknown;
+    } | undefined;
+    await route.fulfill({
+      json: apiEnvelope({
+        messageId: "mock-opening-message",
+        created: true,
+        openingMessage:
+          typeof body?.openingMessage === "string"
+            ? body.openingMessage
+            : "Hello",
+        createdAt: "2026-07-23T00:00:00Z",
+      }),
+    });
+  });
+
   await page.route("**/api/chat/history**", async (route) => {
     const response = options.paidVoiceInsufficientCreditsFlow
       ? paidVoiceHistoryResponse
@@ -44,7 +61,21 @@ export async function registerChatMocks(page: Page, options: ChatMockOptions, st
       await route.fulfill({ status: 401, json: { message: "expired" } });
       return;
     }
-    const response = options.paidImageFlow && message.includes("给我发图片")
+    const response = message.includes("private album offer test")
+      ? {
+          ...chatSendResponse,
+          reply: "You always know how to make me smile.",
+          messageId: "commercial-action-message",
+          commercialAction: {
+            actionId: "commercial-action-1",
+            type: "privateAlbumOffer",
+            copy: "There are more private photos waiting for you.",
+            ctaLabel: "Open private zone",
+            target: "privateZone",
+            ruleId: "private_album_after_appearance_praise",
+          },
+        }
+      : options.paidImageFlow && message.includes("给我发图片")
       ? paidImageChatSendResponse
       : options.chatLimitTriggerAt != null && sendCount >= options.chatLimitTriggerAt
         ? createWeeklyLimitChatSendResponse(sendCount, options.chatLimitTriggerAt)

e2e/specs/mock/chat/commercial-action-navigation.spec.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import {
+  clearBrowserState,
+  enterChatFromSplash,
+} from "@e2e/fixtures/test-helpers";
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("renders a backend commercial action and opens the private zone", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page);
+
+  const input = page.getByRole("textbox", { name: "Message" });
+  await expect(input).toBeEnabled();
+  await input.fill("private album offer test");
+  await input.press("Enter");
+
+  const offer = page.getByLabel("Open private zone");
+  await expect(offer).toContainText(
+    "There are more private photos waiting for you.",
+  );
+  await offer.getByRole("button", { name: "Open private zone" }).click();
+
+  await expect(page).toHaveURL(/\/characters\/elio\/private-zone$/);
+});

e2e/specs/mock/favorite-menu-navigation.spec.ts

@@ -0,0 +1,198 @@
+import path from "node:path";
+
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { e2eEmailUser } from "@e2e/fixtures/data/auth";
+import { chatCharactersResponse } from "@e2e/fixtures/data/character";
+import {
+  emptyChatHistoryResponse,
+  emptyChatPreviewsResponse,
+} from "@e2e/fixtures/data/chat";
+import { paymentPlansResponse } from "@e2e/fixtures/data/payment";
+import { userEntitlementsResponse } from "@e2e/fixtures/data/user";
+import {
+  defaultCharacterChatPath,
+  defaultCharacterSplashPath,
+  seedEmailSession,
+} from "@e2e/fixtures/helpers/auth";
+
+const previewDirectory = path.join(
+  process.cwd(),
+  ".codex",
+  "artifacts",
+  "frontend-preview",
+  "2026-07-22",
+  "favorite-menu",
+);
+
+test.beforeEach(async ({ page }) => {
+  await registerFavoriteMenuMocks(page);
+});
+
+test("favorite entry and three-tab Menu navigation render on the real pages", async ({
+  page,
+}, testInfo) => {
+  const mobile = testInfo.project.name.includes("mobile");
+  await page.setViewportSize(
+    mobile ? { width: 390, height: 844 } : { width: 1440, height: 900 },
+  );
+  const browserErrors = collectBrowserErrors(page);
+
+  await seedEmailSession(page);
+  await page.goto(defaultCharacterChatPath);
+
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: /First recharge offer, 50% off/i }),
+  ).toBeVisible();
+  await expect(page.getByRole("button", { name: "Profile" })).toHaveCount(0);
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-chat.png`);
+
+  await page.goto(defaultCharacterSplashPath);
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  const navigation = page.getByRole("navigation", {
+    name: "Primary navigation",
+  });
+  await expect(navigation).toContainText("Chat");
+  await expect(navigation).toContainText("Private Zone");
+  await expect(navigation).toContainText("Menu");
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-splash.png`);
+
+  await page.goto("/characters/elio/private-zone");
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await savePreview(
+    page,
+    `${mobile ? "mobile" : "desktop"}-private-zone.png`,
+  );
+
+  await page.getByRole("button", { name: "Menu" }).click();
+  await expect(page.getByRole("heading", { name: "Menu" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Menu" })).toHaveAttribute(
+    "aria-current",
+    "page",
+  );
+  await savePreview(page, `${mobile ? "mobile" : "desktop"}-menu.png`);
+
+  if (mobile) {
+    await page.evaluate(() => {
+      localStorage.setItem("cozsweet:favorite_entry", "1");
+    });
+    await page.goto(defaultCharacterChatPath);
+    await expect(page.getByRole("button", { name: "Download" })).toBeVisible();
+    await savePreview(page, "mobile-android-external-chat-download.png");
+
+    await page.addInitScript(() => {
+      Object.defineProperty(navigator, "userAgent", {
+        configurable: true,
+        value:
+          "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1",
+      });
+    });
+    await page.goto(defaultCharacterChatPath);
+    await expect(page.getByRole("button", { name: "Saved" })).toBeVisible();
+    await savePreview(page, "mobile-ios-external-chat-saved.png");
+  }
+
+  expect(browserErrors.filter(isFeatureRuntimeError)).toEqual([]);
+});
+
+async function registerFavoriteMenuMocks(page: Page): Promise<void> {
+  await mockCoreApis(page);
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        ...paymentPlansResponse,
+        isFirstRecharge: true,
+      }),
+    });
+  });
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ items: [], creditBalance: 80 }),
+    });
+  });
+  await page.context().route("**/api/**", async (route) => {
+    const pathname = new URL(route.request().url()).pathname;
+    if (pathname === "/api/auth/session") {
+      await route.fulfill({
+        json: {
+          expires: "2099-12-31T23:59:59.000Z",
+          user: { email: null, image: null, name: null },
+        },
+      });
+      return;
+    }
+    if (pathname === "/api/characters") {
+      await route.fulfill({ json: apiEnvelope(chatCharactersResponse) });
+      return;
+    }
+    if (pathname === "/api/user/profile") {
+      await route.fulfill({ json: apiEnvelope(e2eEmailUser) });
+      return;
+    }
+    if (pathname === "/api/user/entitlements") {
+      await route.fulfill({ json: apiEnvelope(userEntitlementsResponse) });
+      return;
+    }
+    if (pathname === "/api/chat/history") {
+      await route.fulfill({ json: apiEnvelope(emptyChatHistoryResponse) });
+      return;
+    }
+    if (pathname === "/api/chat/previews") {
+      await route.fulfill({ json: apiEnvelope(emptyChatPreviewsResponse) });
+      return;
+    }
+    if (pathname === "/api/payment/plans") {
+      await route.fulfill({
+        json: apiEnvelope({
+          ...paymentPlansResponse,
+          isFirstRecharge: true,
+        }),
+      });
+      return;
+    }
+    if (pathname === "/api/payment/vip-status") {
+      await route.fulfill({
+        json: apiEnvelope({ isVip: false, expiresAt: null }),
+      });
+      return;
+    }
+    if (pathname === "/api/private-zone/albums") {
+      await route.fulfill({
+        json: apiEnvelope({ items: [], creditBalance: 80 }),
+      });
+      return;
+    }
+    await route.fallback();
+  });
+}
+
+function collectBrowserErrors(page: Page): string[] {
+  const errors: string[] = [];
+  page.on("pageerror", (error) => errors.push(error.message));
+  page.on("console", (message) => {
+    if (message.type() === "error") errors.push(message.text());
+  });
+  return errors;
+}
+
+function isFeatureRuntimeError(message: string): boolean {
+  const isKnownLocalPreviewDependencyError =
+    message.includes("[ApiLoggingInterceptor]") ||
+    message.includes("[next-auth][error][CLIENT_FETCH_ERROR]") ||
+    message.includes("[Result] Result.wrap caught exception");
+  return !isKnownLocalPreviewDependencyError;
+}
+
+async function savePreview(page: Page, fileName: string): Promise<void> {
+  if (process.env.FRONTEND_PREVIEW_SCREENSHOTS !== "1") return;
+  await page.screenshot({
+    path: path.join(previewDirectory, fileName),
+    animations: "disabled",
+  });
+}

e2e/specs/mock/multi-role-commercial.spec.ts

@@ -13,6 +13,7 @@ const characters = [
     displayName: "Elio Silvestri",
     shortName: "Elio",
     cover: "elio.png",
+    splashCover: "elio.png",
   },
   {
     id: "maya-tan",
@@ -20,6 +21,7 @@ const characters = [
     displayName: "Maya Tan",
     shortName: "Maya",
     cover: "maya.webp",
+    splashCover: "maya-home.webp",
   },
   {
     id: "nayeli-cervantes",
@@ -27,6 +29,7 @@ const characters = [
     displayName: "Nayeli Cervantes",
     shortName: "Nayeli",
     cover: "nayeli.webp",
+    splashCover: "nayeli.webp",
   },
 ] as const;
 
@@ -56,9 +59,11 @@ for (const character of characters) {
 
     await page.goto(`/characters/${character.slug}/splash`);
 
-    const cover = page.locator(`img[src*="${character.cover}"]`);
+    const cover = page.locator(`img[src*="${character.splashCover}"]`);
     await expect(cover).toBeVisible();
-    await expect(page.getByText(character.displayName).last()).toBeVisible();
+    await expect(
+      page.getByRole("navigation", { name: "Primary navigation" }),
+    ).toContainText("Private Zone");
     await expect
       .poll(() =>
         cover.evaluate((image: HTMLImageElement) =>

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

@@ -82,6 +82,7 @@ describe("core Tailwind components", () => {
         privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
         onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
     const privateZoneHtml = renderToStaticMarkup(
@@ -91,6 +92,7 @@ describe("core Tailwind components", () => {
         privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
         onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
 
@@ -107,5 +109,7 @@ describe("core Tailwind components", () => {
     expect(privateZoneHtml).toContain(
       'data-analytics-key="navigation.private_zone"',
     );
+    expect(chatHtml).toContain('data-analytics-key="navigation.menu"');
+    expect(chatHtml).toContain("<span>Menu</span>");
   });
 });

src/app/_components/core/app-bottom-nav.module.css

@@ -4,7 +4,7 @@
   left: 50%;
   z-index: 30;
   display: grid;
-  grid-template-columns: 1fr 1fr;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   box-sizing: border-box;
   width: min(100vw, var(--app-max-width, 540px));
   min-height: calc(

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

@@ -1,10 +1,10 @@
 "use client";
 
-import { Camera, MessageCircle } from "lucide-react";
+import { Camera, Menu as MenuIcon, MessageCircle } from "lucide-react";
 
 import styles from "./app-bottom-nav.module.css";
 
-export type AppBottomNavItem = "chat" | "privateZone";
+export type AppBottomNavItem = "chat" | "privateZone" | "menu";
 export type AppBottomNavVariant = "warm" | "dark";
 
 export interface AppBottomNavProps {
@@ -13,6 +13,7 @@ export interface AppBottomNavProps {
   privateZoneLabel: string;
   onChatClick: () => void;
   onPrivateZoneClick: () => void;
+  onMenuClick: () => void;
 }
 
 export function AppBottomNav({
@@ -21,6 +22,7 @@ export function AppBottomNav({
   privateZoneLabel,
   onChatClick,
   onPrivateZoneClick,
+  onMenuClick,
 }: AppBottomNavProps) {
   return (
     <nav className={getRootClass(variant)} aria-label="Primary navigation">
@@ -46,6 +48,17 @@ export function AppBottomNav({
         <Camera size={20} aria-hidden="true" />
         <span>{privateZoneLabel}</span>
       </button>
+      <button
+        type="button"
+        data-analytics-key="navigation.menu"
+        data-analytics-label="Menu navigation"
+        className={getButtonClass(activeItem === "menu")}
+        aria-current={activeItem === "menu" ? "page" : undefined}
+        onClick={onMenuClick}
+      >
+        <MenuIcon size={20} aria-hidden="true" />
+        <span>Menu</span>
+      </button>
     </nav>
   );
 }

src/app/_components/core/favorite-entry-button.module.css

@@ -0,0 +1,96 @@
+.wrap {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  justify-content: flex-end;
+}
+
+.button {
+  display: inline-flex;
+  min-width: var(--responsive-icon-button-size, 42px);
+  height: var(--responsive-icon-button-size, 42px);
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  box-sizing: border-box;
+  padding: 0 11px;
+  border: 1px solid var(--favorite-border);
+  border-radius: 999px;
+  background: var(--favorite-background);
+  color: var(--favorite-color);
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 850;
+  line-height: 1;
+  box-shadow: var(--favorite-shadow);
+  backdrop-filter: blur(16px);
+  transition: background 160ms ease, transform 160ms ease,
+    box-shadow 160ms ease;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.dark {
+  --favorite-background: rgba(18, 15, 24, 0.72);
+  --favorite-border: rgba(255, 255, 255, 0.22);
+  --favorite-color: #ffffff;
+  --favorite-shadow: 0 10px 26px rgba(0, 0, 0, 0.24);
+}
+
+.light {
+  --favorite-background: rgba(255, 255, 255, 0.88);
+  --favorite-border: rgba(43, 27, 34, 0.1);
+  --favorite-color: #34272c;
+  --favorite-shadow: 0 10px 24px rgba(74, 48, 58, 0.1);
+}
+
+.favorite {
+  width: var(--responsive-icon-button-size, 42px);
+  padding: 0;
+}
+
+.download {
+  color: #ffffff;
+  background: linear-gradient(135deg, #ff76ab, #f84d96);
+  border-color: rgba(255, 255, 255, 0.42);
+  box-shadow: 0 10px 25px rgba(248, 77, 150, 0.3);
+}
+
+.saved {
+  color: #f84d96;
+}
+
+.button:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 13px 30px rgba(0, 0, 0, 0.2);
+}
+
+.button:active {
+  transform: translateY(1px) scale(0.98);
+}
+
+.button:focus-visible {
+  outline: 2px solid #ffffff;
+  outline-offset: 3px;
+}
+
+.light:focus-visible {
+  outline-color: #f84d96;
+}
+
+.hint {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  z-index: 45;
+  width: max-content;
+  max-width: min(72vw, 250px);
+  padding: 8px 10px;
+  border-radius: 10px;
+  background: rgba(22, 18, 25, 0.94);
+  color: #ffffff;
+  font-size: 11px;
+  font-weight: 700;
+  line-height: 1.3;
+  box-shadow: 0 10px 26px rgba(0, 0, 0, 0.24);
+}

src/app/_components/core/favorite-entry-button.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Download, Star } from "lucide-react";
+
+import { openChatInExternalBrowser } from "@/lib/chat/chat_external_browser";
+import {
+  hasPersistedFavoriteEntryIntent,
+  resolveFavoriteEntryMode,
+  type FavoriteEntryMode,
+} from "@/lib/navigation/favorite_entry";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { pwaUtil } from "@/utils/pwa";
+
+import styles from "./favorite-entry-button.module.css";
+
+export interface FavoriteEntryButtonProps {
+  characterSlug: string;
+  tone?: "dark" | "light";
+}
+
+export function FavoriteEntryButton({
+  characterSlug,
+  tone = "dark",
+}: FavoriteEntryButtonProps) {
+  const [mode, setMode] = useState<FavoriteEntryMode>("favorite");
+  const [installHint, setInstallHint] = useState(false);
+
+  useEffect(() => {
+    const updateMode = () => {
+      setMode(
+        resolveFavoriteEntryMode({
+          hasFavoriteIntent: hasPersistedFavoriteEntryIntent(),
+          isAndroid: PlatformDetector.isAndroid(),
+          isIOS: PlatformDetector.isIOS(),
+          isInAppBrowser: BrowserDetector.isInAppBrowser(),
+          isInstalled: pwaUtil.isInstalled(),
+        }),
+      );
+    };
+
+    pwaUtil.prepareInstallPrompt();
+    updateMode();
+    const unsubscribe = pwaUtil.subscribe(updateMode);
+    return unsubscribe;
+  }, []);
+
+  const handleClick = async (): Promise<void> => {
+    if (mode === "favorite") {
+      await openChatInExternalBrowser({ characterSlug });
+      return;
+    }
+
+    if (mode === "download") {
+      pwaUtil.prepareInstallPrompt();
+      const result = await pwaUtil.install();
+      if (result === "accepted" || pwaUtil.isInstalled()) {
+        setMode("saved");
+        setInstallHint(false);
+        return;
+      }
+      if (result === "unavailable") setInstallHint(true);
+    }
+  };
+
+  const label = getFavoriteEntryLabel(mode);
+
+  return (
+    <div className={styles.wrap}>
+      <button
+        type="button"
+        data-analytics-key={`favorite.${mode}`}
+        data-analytics-label={label}
+        className={[styles.button, styles[tone], styles[mode]]
+          .filter(Boolean)
+          .join(" ")}
+        aria-label={label}
+        aria-pressed={mode === "saved"}
+        onClick={() => void handleClick()}
+      >
+        {mode === "download" ? (
+          <Download size={16} strokeWidth={2.4} aria-hidden="true" />
+        ) : (
+          <Star
+            size={21}
+            strokeWidth={2.3}
+            fill={mode === "saved" ? "currentColor" : "none"}
+            aria-hidden="true"
+          />
+        )}
+        {mode === "favorite" ? null : <span>{label}</span>}
+      </button>
+      {installHint ? (
+        <span className={styles.hint} role="status">
+          Chrome menu → Add to Home screen
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+function getFavoriteEntryLabel(mode: FavoriteEntryMode): string {
+  if (mode === "download") return "Download";
+  if (mode === "saved") return "Saved";
+  return "Save CozSweet";
+}

src/app/_components/core/index.ts

@@ -5,6 +5,7 @@
 export * from "./app-bottom-nav";
 export * from "./bottom-sheet";
 export * from "./checkbox";
+export * from "./favorite-entry-button";
 export * from "./loading-indicator";
 export * from "./mobile-shell";
 export * from "./page-loading-fallback";

src/app/chat/chat-screen.tsx

@@ -18,6 +18,8 @@ import { clearPendingChatNavigation } from "@/lib/navigation/chat_unlock_session
 import { buildGlobalPageUrl } from "@/router/global-route-context";
 import { resolveAuthenticatedNavigation } from "@/router/navigation-resolver";
 import { getCharacterRoutes, ROUTES } from "@/router/routes";
+import type { CommercialAction } from "@/data/schemas/chat";
+import { behaviorAnalytics } from "@/lib/analytics";
 
 import { MobileShell } from "@/app/_components/core";
 
@@ -38,7 +40,6 @@ import {
 } from "./chat-image-overlay-url";
 import {
   deriveIsGuest,
-  shouldStartExternalBrowserPrompt,
 } from "./chat-screen.helpers";
 import { useFirstRechargeOfferBanner } from "./hooks/use-first-recharge-offer-banner";
 import { useChatUnlockCoordinator } from "./hooks/use-chat-unlock-coordinator";
@@ -118,12 +119,6 @@ export function ChatScreen() {
   });
   const shouldShowPwaInstall =
     state.historyLoaded && state.historyMessages.length >= 10;
-  const shouldShowBrowserHint = shouldStartExternalBrowserPrompt({
-    hasInitialized: authState.hasInitialized,
-    isLoading: authState.isLoading,
-    loginStatus: authState.loginStatus,
-  });
-
   useChatGuestLogin({
     dispatch: authDispatch,
     hasInitialized: authState.hasInitialized,
@@ -257,6 +252,38 @@ export function ChatScreen() {
     router.push(characterRoutes.privateZone);
   }
 
+  function handleCommercialAction(action: CommercialAction): void {
+    behaviorAnalytics.elementClick(
+      "chat.commercial_action.open",
+      action.ctaLabel,
+      {
+        actionId: action.actionId,
+        actionType: action.type,
+        characterId: state.characterId,
+        ruleId: action.ruleId,
+        target: action.target,
+      },
+    );
+    router.push(
+      action.target === "giftCatalog"
+        ? characterRoutes.tip
+        : characterRoutes.privateZone,
+    );
+  }
+
+  function handleCommercialActionDismiss(action: CommercialAction): void {
+    behaviorAnalytics.elementClick(
+      "chat.commercial_action.dismiss",
+      "Dismiss commercial action",
+      {
+        actionId: action.actionId,
+        actionType: action.type,
+        characterId: state.characterId,
+        ruleId: action.ruleId,
+      },
+    );
+  }
+
   return (
     <MobileShell>
       <div
@@ -276,13 +303,13 @@ export function ChatScreen() {
         <div className="relative z-1 flex min-h-0 flex-[1_1_auto] flex-col">
           <ChatHeader
             isGuest={isGuest}
-            showBrowserHint={shouldShowBrowserHint}
             offerBanner={
               <FirstRechargeOfferBanner
                 visible={firstRechargeOfferBanner.visible}
                 discountPercent={firstRechargeOfferBanner.discountPercent}
                 onClick={firstRechargeOfferBanner.claim}
                 onClose={firstRechargeOfferBanner.close}
+                variant="compact"
               />
             }
           />
@@ -305,6 +332,8 @@ export function ChatScreen() {
             onOpenImage={handleOpenImage}
             onUserAvatarClick={handleOpenUserProfile}
             onCharacterAvatarClick={handleOpenCharacterPrivateZone}
+            onCommercialAction={handleCommercialAction}
+            onCommercialActionDismiss={handleCommercialActionDismiss}
             onLoadMoreHistory={() => {
               chatDispatch({ type: "ChatLoadMoreHistoryRequested" });
             }}

src/app/chat/components/__tests__/commercial-action-card.test.tsx

@@ -0,0 +1,26 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { CommercialActionCard } from "../commercial-action-card";
+
+describe("CommercialActionCard", () => {
+  it("renders a private-zone offer with a usable CTA", () => {
+    const html = renderToStaticMarkup(
+      <CommercialActionCard
+        action={{
+          actionId: "action-1",
+          type: "privateAlbumOffer",
+          copy: "There are more private photos waiting for you.",
+          ctaLabel: "Open private zone",
+          target: "privateZone",
+          ruleId: "private_album_after_appearance_praise",
+        }}
+      />,
+    );
+
+    expect(html).toContain('data-commercial-action="privateAlbumOffer"');
+    expect(html).toContain("There are more private photos waiting for you.");
+    expect(html).toContain("Open private zone");
+    expect(html).toContain('aria-label="Dismiss offer"');
+  });
+});

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

@@ -242,12 +242,6 @@ describe("chat Tailwind components", () => {
     const memberHtml = renderWithCharacter(
       <ChatHeader isGuest={false} offerBanner={<div>Offer</div>} />,
     );
-    const memberWithHintHtml = renderWithCharacter(
-      <ChatHeader isGuest={false} showBrowserHint />,
-    );
-    const guestWithHintHtml = renderWithCharacter(
-      <ChatHeader isGuest={true} showBrowserHint />,
-    );
 
     expect(guestHtml).toContain('aria-label="Sign up to unlock more features"');
     expect(guestHtml).toContain("bg-accent");
@@ -257,50 +251,33 @@ describe("chat Tailwind components", () => {
     expect(guestHtml).toContain('data-analytics-key="chat.back_to_home"');
     expect(guestHtml).toContain("px-(--chat-inline-padding,16px)");
     expect(guestHtml).not.toContain('aria-label="Profile"');
+    expect(guestHtml).toContain('aria-label="Save CozSweet"');
     expect(memberHtml).toContain("Offer");
     expect(memberHtml).toContain('href="/characters/elio/splash"');
     expect(memberHtml).toContain('aria-label="Back to home"');
-    expect(memberHtml).toContain('aria-label="Profile"');
+    expect(memberHtml).toContain('aria-label="Save CozSweet"');
-    expect(memberHtml).toContain('data-analytics-key="chat.open_profile"');
+    expect(memberHtml).toContain('data-analytics-key="favorite.favorite"');
     expect(memberHtml).toContain('data-analytics-key="chat.back_to_home"');
     expect(memberHtml).toContain("px-(--chat-inline-padding,16px)");
     expect(memberHtml).not.toContain("px-(--spacing-md,12px)");
-    expect(memberHtml).toContain("bg-[rgba(13,11,20,0.7)]");
+    expect(memberHtml).toContain(
-    expect(memberHtml).toContain("size-(--responsive-icon-button-size,42px)");
-    expect(memberHtml).toContain("lucide-user-round");
-    expect(memberWithHintHtml).toContain(
-      'data-analytics-key="chat.external_browser_hint"',
-    );
-    expect(memberWithHintHtml).toContain(
       "grid-cols-[auto_minmax(0,1fr)_auto]",
     );
-    expect(memberWithHintHtml.indexOf('aria-label="Back to home"')).toBeLessThan(
+    expect(memberHtml).not.toContain(
-      memberWithHintHtml.indexOf(
-        'data-analytics-key="chat.external_browser_hint"',
-      ),
-    );
-    expect(
-      memberWithHintHtml.indexOf(
-        'data-analytics-key="chat.external_browser_hint"',
-      ),
-    ).toBeLessThan(memberWithHintHtml.indexOf('aria-label="Profile"'));
-    expect(guestWithHintHtml).not.toContain(
       'data-analytics-key="chat.external_browser_hint"',
     );
   });
 
-  it("renders the user avatar in the ChatHeader Profile action", () => {
+  it("replaces the ChatHeader Profile avatar with the favorite action", () => {
     userMocks.avatarUrl = "/images/avatar/profile-user.png";
 
     const html = renderWithCharacter(<ChatHeader isGuest={false} />);
 
-    expect(html).toContain("%2Fimages%2Favatar%2Fprofile-user.png");
+    expect(html).not.toContain("%2Fimages%2Favatar%2Fprofile-user.png");
-    expect(html).toContain('aria-label="Profile"');
+    expect(html).not.toContain('aria-label="Profile"');
-    expect(html).toContain('data-analytics-key="chat.open_profile"');
+    expect(html).not.toContain('data-analytics-key="chat.open_profile"');
-    expect(html).toContain(
+    expect(html).toContain('aria-label="Save CozSweet"');
-      "var(--responsive-icon-button-size, 42px)",
+    expect(html).toContain("lucide-star");
-    );
-    expect(html).not.toContain("lucide-user-round");
   });
 
   it("links guest chat back to the active character splash", () => {
@@ -315,6 +292,7 @@ describe("chat Tailwind components", () => {
 
     expect(html).toContain('href="/characters/maya/splash"');
     expect(html).not.toContain('aria-label="Profile"');
+    expect(html).toContain('aria-label="Save CozSweet"');
     expect(html).not.toContain(
       'data-analytics-key="chat.external_browser_hint"',
     );

src/app/chat/components/chat-area.module.css

@@ -131,6 +131,64 @@
   align-items: flex-end;
 }
 
+.commercialAction {
+  width: min(100%, 286px);
+  padding: 12px;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 8px;
+  background: rgba(25, 21, 31, 0.92);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.2);
+}
+
+.commercialActionHeader {
+  display: flex;
+  min-height: 24px;
+  align-items: center;
+  justify-content: space-between;
+  color: #f4b860;
+}
+
+.commercialActionDismiss {
+  display: inline-flex;
+  width: 28px;
+  height: 28px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  background: transparent;
+  color: rgba(255, 255, 255, 0.66);
+  cursor: pointer;
+}
+
+.commercialActionCopy {
+  margin: 7px 0 11px;
+  color: rgba(255, 255, 255, 0.9);
+  font-size: var(--responsive-caption, var(--font-size-sm, 13px));
+  line-height: 1.45;
+}
+
+.commercialActionButton {
+  display: inline-flex;
+  min-height: 38px;
+  max-width: 100%;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  padding: 8px 12px;
+  border: 0;
+  border-radius: 6px;
+  background: #f4b860;
+  color: #201710;
+  cursor: pointer;
+  font-size: var(--responsive-caption, var(--font-size-sm, 13px));
+  font-weight: 700;
+}
+
+.commercialActionButton span {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
 .bubbleAi {
   max-width: var(--chat-bubble-max-width, 75%);
   background: var(--color-bubble-ai, rgba(255, 255, 255, 0.08));

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

@@ -24,6 +24,7 @@ import {
 import { LoaderCircle } from "lucide-react";
 
 import type { UiMessage } from "@/stores/chat/ui-message";
+import type { CommercialAction } from "@/data/schemas/chat";
 import { usePullToRefresh } from "@/hooks/use-pull-to-refresh";
 
 import {
@@ -61,6 +62,8 @@ export interface ChatAreaProps {
   onLoadMoreHistory?: () => void;
   onUserAvatarClick?: () => void;
   onCharacterAvatarClick?: () => void;
+  onCommercialAction?: (action: CommercialAction) => void;
+  onCommercialActionDismiss?: (action: CommercialAction) => void;
 }
 
 type ChatMessageAction = (
@@ -85,6 +88,8 @@ export function ChatArea({
   onLoadMoreHistory,
   onUserAvatarClick,
   onCharacterAvatarClick,
+  onCommercialAction,
+  onCommercialActionDismiss,
 }: ChatAreaProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
@@ -257,6 +262,8 @@ export function ChatArea({
           onOpenImage,
           onUserAvatarClick,
           onCharacterAvatarClick,
+          onCommercialAction,
+          onCommercialActionDismiss,
         )}
 
         {isReplyingAI ? (
@@ -295,6 +302,8 @@ function renderMessagesWithDateHeaders(
   onOpenImage?: (displayMessageId: string) => void,
   onUserAvatarClick?: () => void,
   onCharacterAvatarClick?: () => void,
+  onCommercialAction?: (action: CommercialAction) => void,
+  onCommercialActionDismiss?: (action: CommercialAction) => void,
 ) {
   return buildChatRenderItems(messages, getMessageKey).map((item) =>
     item.type === "date" ? (
@@ -314,6 +323,7 @@ function renderMessagesWithDateHeaders(
         lockReason={item.message.lockReason}
         lockedPrivate={item.message.lockedPrivate}
         privateMessageHint={item.message.privateMessageHint}
+        commercialAction={item.message.commercialAction}
         isUnlockingMessage={
           isUnlockingMessage === true &&
           item.message.displayId === unlockingMessageId
@@ -324,6 +334,8 @@ function renderMessagesWithDateHeaders(
         onOpenImage={onOpenImage}
         onUserAvatarClick={onUserAvatarClick}
         onCharacterAvatarClick={onCharacterAvatarClick}
+        onCommercialAction={onCommercialAction}
+        onCommercialActionDismiss={onCommercialActionDismiss}
       />
     ),
   );

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

@@ -2,37 +2,31 @@
 /**
  * ChatHeader 顶部栏
  *
- * Profile 优先展示用户头像；头像缺失时回退到 lucide-react <UserRound />。
+ * 顶部保持返回、首充优惠、收藏入口三段结构。
  */
 import type { ReactNode } from "react";
-import { Lock, UserRound } from "lucide-react";
+import { Lock } from "lucide-react";
 
-import { BackButton, UserMessageAvatar } from "@/app/_components";
+import { BackButton } from "@/app/_components";
-import { useActiveCharacterRoutes } from "@/providers/character-provider";
+import { FavoriteEntryButton } from "@/app/_components/core";
-import { buildGlobalPageUrl } from "@/router/global-route-context";
+import {
-import { ROUTES } from "@/router/routes";
+  useActiveCharacter,
+  useActiveCharacterRoutes,
+} from "@/providers/character-provider";
 import { useAppNavigator } from "@/router/use-app-navigator";
-import { useUserSelector } from "@/stores/user/user-context";
-
-import { BrowserHintOverlay } from "./browser-hint-overlay";
 
 export interface ChatHeaderProps {
   isGuest: boolean;
   offerBanner?: ReactNode;
-  showBrowserHint?: boolean;
 }
 
 export function ChatHeader({
   isGuest,
   offerBanner,
-  showBrowserHint = false,
 }: ChatHeaderProps) {
   const navigator = useAppNavigator();
+  const character = useActiveCharacter();
   const characterRoutes = useActiveCharacterRoutes();
-  const avatarUrl = useUserSelector((state) => state.context.avatarUrl);
-  const handleOpenProfile = () => {
-    navigator.push(buildGlobalPageUrl(ROUTES.profile, characterRoutes.chat));
-  };
 
   return (
     <header className="flex shrink-0 flex-col items-stretch bg-transparent p-0">
@@ -52,17 +46,9 @@ export function ChatHeader({
           />
           <span>Sign up to unlock more features</span>
         </button>
-      ) : (
+      ) : null}
-        offerBanner
-      )}
 
-      <div
+      <div className="grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-(--spacing-sm,8px) px-(--chat-inline-padding,16px) py-(--spacing-sm,8px)">
-        className={
-          isGuest
-            ? "flex items-center px-(--chat-inline-padding,16px) py-(--spacing-sm,8px)"
-            : "grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-(--spacing-sm,8px) px-(--chat-inline-padding,16px) py-(--spacing-sm,8px)"
-        }
-      >
         <BackButton
           href={characterRoutes.splash}
           variant="dark"
@@ -70,34 +56,12 @@ export function ChatHeader({
           analyticsKey="chat.back_to_home"
         />
 
-        {!isGuest ? (
+        <div className="flex min-w-0 justify-center">{offerBanner}</div>
-          <>
-            <div className="flex min-w-0 justify-center">
-              {showBrowserHint ? <BrowserHintOverlay /> : null}
-            </div>
 
-            {avatarUrl ? (
+        <FavoriteEntryButton
-              <UserMessageAvatar
+          characterSlug={character.slug}
-                avatarUrl={avatarUrl}
+          tone="dark"
-                size="var(--responsive-icon-button-size, 42px)"
-                actionLabel="Profile"
-                analyticsKey="chat.open_profile"
-                onClick={handleOpenProfile}
         />
-            ) : (
-              <button
-                type="button"
-                data-analytics-key="chat.open_profile"
-                data-analytics-label="Open profile"
-                className="flex size-(--responsive-icon-button-size,42px) cursor-pointer items-center justify-center rounded-full border border-[rgba(255,255,255,0.12)] bg-[rgba(13,11,20,0.7)] text-(--color-text-primary,#fff) shadow-[0_10px_24px_rgba(0,0,0,0.2)] backdrop-blur-md transition-[background,transform] duration-150 hover:bg-[rgba(28,24,39,0.82)] active:scale-96 focus-visible:outline-2 focus-visible:outline-offset-3 focus-visible:outline-[#f657a0]"
-                onClick={handleOpenProfile}
-                aria-label="Profile"
-              >
-                <UserRound size={24} aria-hidden="true" />
-              </button>
-            )}
-          </>
-        ) : null}
       </div>
     </header>
   );

src/app/chat/components/commercial-action-card.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from "react";
+import { ArrowRight, Gift, Images, X } from "lucide-react";
+
+import type { CommercialAction } from "@/data/schemas/chat";
+
+import styles from "./chat-area.module.css";
+
+export interface CommercialActionCardProps {
+  action: CommercialAction;
+  onActivate?: (action: CommercialAction) => void;
+  onDismiss?: (action: CommercialAction) => void;
+}
+
+export function CommercialActionCard({
+  action,
+  onActivate,
+  onDismiss,
+}: CommercialActionCardProps) {
+  const [dismissed, setDismissed] = useState(false);
+  if (dismissed) return null;
+
+  const Icon = action.type === "giftOffer" ? Gift : Images;
+
+  return (
+    <aside
+      className={styles.commercialAction}
+      aria-label={action.ctaLabel}
+      data-commercial-action={action.type}
+    >
+      <div className={styles.commercialActionHeader}>
+        <Icon size={18} aria-hidden="true" />
+        <button
+          type="button"
+          className={styles.commercialActionDismiss}
+          title="Dismiss offer"
+          aria-label="Dismiss offer"
+          onClick={() => {
+            setDismissed(true);
+            onDismiss?.(action);
+          }}
+        >
+          <X size={16} aria-hidden="true" />
+        </button>
+      </div>
+      <p className={styles.commercialActionCopy}>{action.copy}</p>
+      <button
+        type="button"
+        className={styles.commercialActionButton}
+        onClick={() => onActivate?.(action)}
+      >
+        <span>{action.ctaLabel}</span>
+        <ArrowRight size={17} aria-hidden="true" />
+      </button>
+    </aside>
+  );
+}

src/app/chat/components/first-recharge-offer-banner.module.css

@@ -121,8 +121,73 @@
   cursor: pointer;
 }
 
+.compactButton {
+  display: grid;
+  min-width: 0;
+  max-width: 224px;
+  min-height: 44px;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 7px;
+  padding: 5px 8px;
+  overflow: hidden;
+  border: 1px solid rgba(255, 255, 255, 0.42);
+  border-radius: 16px;
+  background:
+    radial-gradient(circle at 15% 0%, rgba(255, 255, 255, 0.68), transparent 38%),
+    linear-gradient(135deg, #fff0b8 0%, #ffd0df 50%, #ff6cab 100%);
+  color: #2c111d;
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+  box-shadow: 0 9px 24px rgba(114, 21, 63, 0.2);
+  animation: firstRechargeBannerIn 260ms ease-out both;
+}
+
+.compactIcon {
+  display: inline-flex;
+  width: 28px;
+  height: 28px;
+  align-items: center;
+  justify-content: center;
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.55);
+  color: #f90073;
+}
+
+.compactCopy {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 2px;
+  font-size: 10px;
+  font-weight: 800;
+  line-height: 1.05;
+  text-transform: uppercase;
+}
+
+.compactCopy span,
+.compactCopy strong {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.compactCopy span {
+  color: rgba(44, 17, 29, 0.68);
+  letter-spacing: 0.03em;
+}
+
+.compactCopy strong {
+  color: #ec006d;
+  font-size: 15px;
+  font-weight: 950;
+  letter-spacing: -0.02em;
+}
+
 .contentButton:focus-visible,
-.closeButton:focus-visible {
+.closeButton:focus-visible,
+.compactButton:focus-visible {
   outline: 2px solid rgba(255, 255, 255, 0.94);
   outline-offset: -3px;
 }
@@ -144,4 +209,14 @@
     flex-direction: column;
     gap: 2px;
   }
+
+  .compactButton {
+    gap: 5px;
+    padding-inline: 6px;
+  }
+
+  .compactIcon {
+    width: 26px;
+    height: 26px;
+  }
 }

src/app/chat/components/first-recharge-offer-banner.tsx

@@ -9,6 +9,7 @@ export interface FirstRechargeOfferBannerProps {
   discountPercent: number;
   onClick: () => void;
   onClose: () => void;
+  variant?: "banner" | "compact";
 }
 
 export function FirstRechargeOfferBanner({
@@ -16,9 +17,32 @@ export function FirstRechargeOfferBanner({
   discountPercent,
   onClick,
   onClose,
+  variant = "banner",
 }: FirstRechargeOfferBannerProps) {
   if (!visible) return null;
 
+  if (variant === "compact") {
+    return (
+      <button
+        type="button"
+        data-analytics-key="chat.first_recharge_offer"
+        data-analytics-label="Open first recharge offer"
+        className={styles.compactButton}
+        aria-label={`First recharge offer, ${discountPercent}% off`}
+        onClick={onClick}
+      >
+        <span className={styles.compactIcon} aria-hidden="true">
+          <Sparkles size={14} strokeWidth={2.4} />
+        </span>
+        <span className={styles.compactCopy}>
+          <span>First recharge</span>
+          <strong>{discountPercent}% OFF</strong>
+        </span>
+        <ChevronRight size={14} strokeWidth={2.4} aria-hidden="true" />
+      </button>
+    );
+  }
+
   return (
     <section className={styles.banner} aria-label="First recharge offer">
       <button

src/app/chat/components/index.ts

@@ -5,6 +5,7 @@
 export * from "./ai-disclosure-banner";
 export * from "./browser-hint-overlay";
 export * from "./chat-area";
+export * from "./commercial-action-card";
 export * from "./chat-header";
 export * from "./chat-insufficient-credits-banner";
 export * from "./chat-input-bar";

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

@@ -9,6 +9,7 @@
  *   - 用户：[占位 spacer] [Content] [Avatar]
  */
 import { useUserSelector } from "@/stores/user/user-context";
+import type { CommercialAction } from "@/data/schemas/chat";
 
 import { MessageAvatar } from "./message-avatar";
 import { MessageContent } from "./message-content";
@@ -27,6 +28,7 @@ export interface MessageBubbleProps {
   lockReason?: string | null;
   lockedPrivate?: boolean | null;
   privateMessageHint?: string | null;
+  commercialAction?: CommercialAction | null;
   isUnlockingMessage?: boolean;
   onUnlockPrivateMessage?: ChatMessageAction;
   onUnlockVoiceMessage?: ChatMessageAction;
@@ -34,6 +36,8 @@ export interface MessageBubbleProps {
   onOpenImage?: (displayMessageId: string) => void;
   onUserAvatarClick?: () => void;
   onCharacterAvatarClick?: () => void;
+  onCommercialAction?: (action: CommercialAction) => void;
+  onCommercialActionDismiss?: (action: CommercialAction) => void;
 }
 
 type ChatMessageAction = (
@@ -54,6 +58,7 @@ export function MessageBubble({
   lockReason,
   lockedPrivate,
   privateMessageHint,
+  commercialAction,
   isUnlockingMessage,
   onUnlockPrivateMessage,
   onUnlockVoiceMessage,
@@ -61,6 +66,8 @@ export function MessageBubble({
   onOpenImage,
   onUserAvatarClick,
   onCharacterAvatarClick,
+  onCommercialAction,
+  onCommercialActionDismiss,
 }: MessageBubbleProps) {
   const avatarUrl = useUserSelector((state) => state.context.avatarUrl);
 
@@ -89,11 +96,14 @@ export function MessageBubble({
           lockReason={lockReason}
           lockedPrivate={lockedPrivate}
           privateMessageHint={privateMessageHint}
+          commercialAction={commercialAction}
           isUnlockingMessage={isUnlockingMessage}
           onUnlockPrivateMessage={onUnlockPrivateMessage}
           onUnlockVoiceMessage={onUnlockVoiceMessage}
           onUnlockImageMessage={onUnlockImageMessage}
           onOpenImage={onOpenImage}
+          onCommercialAction={onCommercialAction}
+          onCommercialActionDismiss={onCommercialActionDismiss}
         />
         <div className={styles.bubbleAvatarSpacer} aria-hidden="true" />
       </div>

src/app/chat/components/message-content.tsx

@@ -1,4 +1,7 @@
 "use client";
+import type { CommercialAction } from "@/data/schemas/chat";
+
+import { CommercialActionCard } from "./commercial-action-card";
 import { ImageBubble } from "./image-bubble";
 import { LockedImageMessageCard } from "./locked-image-message-card";
 import { PrivateMessageCard } from "./private-message-card";
@@ -19,11 +22,14 @@ export interface MessageContentProps {
   lockReason?: string | null;
   lockedPrivate?: boolean | null;
   privateMessageHint?: string | null;
+  commercialAction?: CommercialAction | null;
   isUnlockingMessage?: boolean;
   onUnlockPrivateMessage?: ChatMessageAction;
   onUnlockVoiceMessage?: ChatMessageAction;
   onUnlockImageMessage?: ChatMessageAction;
   onOpenImage?: (displayMessageId: string) => void;
+  onCommercialAction?: (action: CommercialAction) => void;
+  onCommercialActionDismiss?: (action: CommercialAction) => void;
 }
 
 type ChatMessageAction = (
@@ -46,11 +52,14 @@ export function MessageContent({
   lockReason,
   lockedPrivate,
   privateMessageHint,
+  commercialAction,
   isUnlockingMessage,
   onUnlockPrivateMessage,
   onUnlockVoiceMessage,
   onUnlockImageMessage,
   onOpenImage,
+  onCommercialAction,
+  onCommercialActionDismiss,
 }: MessageContentProps) {
   const hasImage = imageUrl != null && imageUrl.length > 0;
   const hasAudio = audioUrl != null && audioUrl.length > 0;
@@ -125,6 +134,13 @@ export function MessageContent({
           ) : null}
         </>
       )}
+      {isFromAI && commercialAction ? (
+        <CommercialActionCard
+          action={commercialAction}
+          onActivate={onCommercialAction}
+          onDismiss={onCommercialActionDismiss}
+        />
+      ) : null}
     </div>
   );
 }

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

@@ -21,6 +21,10 @@ import {
 } from "@/data/constants/character";
 import { Logger } from "@/utils/logger";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
+import {
+  isFavoriteEntryRequest,
+  persistFavoriteEntryIntent,
+} from "@/lib/navigation/favorite_entry";
 
 const log = new Logger("ExternalEntryPersist");
 
@@ -33,6 +37,7 @@ interface ExternalEntryPersistProps {
   character: string | null;
   mode: string | null;
   promotionType: string | null;
+  favorite: string | null;
 }
 
 export default function ExternalEntryPersist({
@@ -44,6 +49,7 @@ export default function ExternalEntryPersist({
   character,
   mode,
   promotionType,
+  favorite,
 }: ExternalEntryPersistProps) {
   const router = useRouter();
   const authState = useAuthState();
@@ -75,6 +81,9 @@ export default function ExternalEntryPersist({
           ? savePendingChatPromotion(resolvedPromotionType, characterId)
           : clearPendingChatPromotion(),
       ]);
+      if (isFavoriteEntryRequest(favorite)) {
+        persistFavoriteEntryIntent();
+      }
       for (const result of results) {
         if (result.status === "rejected") {
           log.warn(
@@ -96,6 +105,7 @@ export default function ExternalEntryPersist({
     characterId,
     destination,
     deviceId,
+    favorite,
     mode,
     promotionType,
     psid,

src/app/external-entry/page.tsx

@@ -34,6 +34,7 @@ export default async function ExternalEntryPage({
       character={pickParam(params.character)}
       mode={pickParam(params.mode)}
       promotionType={pickParam(params.promotion_type)}
+      favorite={pickParam(params.favorite)}
     />
   );
 }

src/app/private-zone/private-zone-screen.module.css

@@ -26,6 +26,13 @@
   filter: blur(8px);
 }
 
+.favoriteAction {
+  position: absolute;
+  top: calc(var(--app-safe-top, 0px) + 14px);
+  right: calc(var(--app-safe-right, 0px) + 14px);
+  z-index: 5;
+}
+
 .backgroundGlowOne {
   top: 118px;
   right: -82px;

src/app/private-zone/private-zone-screen.tsx

@@ -5,7 +5,13 @@ import Image from "next/image";
 import { useRouter, useSearchParams } from "next/navigation";
 
 import { CharacterAvatar } from "@/app/_components";
-import { AppBottomNav, MobileShell } from "@/app/_components/core";
+import {
+  AppBottomNav,
+  FavoriteEntryButton,
+  MobileShell,
+} from "@/app/_components/core";
+import { buildGlobalPageUrl } from "@/router/global-route-context";
+import { ROUTES } from "@/router/routes";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import {
   useActiveCharacter,
@@ -183,6 +189,12 @@ export function PrivateZoneScreen() {
       <main className={styles.shell}>
         <div className={styles.backgroundGlowOne} />
         <div className={styles.backgroundGlowTwo} />
+        <div className={styles.favoriteAction}>
+          <FavoriteEntryButton
+            characterSlug={character.slug}
+            tone="dark"
+          />
+        </div>
 
         <section className={styles.hero} aria-label={title}>
           <div className={styles.heroCover}>
@@ -275,6 +287,12 @@ export function PrivateZoneScreen() {
             navigator.push(characterRoutes.splash, { scroll: false })
           }
           onPrivateZoneClick={() => undefined}
+          onMenuClick={() =>
+            navigator.push(
+              buildGlobalPageUrl(ROUTES.profile, characterRoutes.chat),
+              { scroll: false },
+            )
+          }
         />
 
         {pendingAlbum ? (

src/app/profile/components/profile-screen.module.css

@@ -3,13 +3,16 @@
   display: flex;
   flex-direction: column;
   gap: var(--page-section-gap, 14px);
-  overflow: hidden;
+  overflow: hidden auto;
   min-height: var(--app-viewport-height, 100dvh);
   box-sizing: border-box;
   padding:
     var(--app-safe-top, 0px)
     calc(var(--page-padding-x, 28px) + var(--app-safe-right, 0px))
-    calc(var(--page-padding-y, 20px) + var(--app-safe-bottom, 0px))
+    calc(
+      var(--page-padding-y, 20px) + var(--app-safe-bottom, 0px) +
+        var(--app-bottom-nav-height, 64px)
+    )
     calc(var(--page-padding-x, 28px) + var(--app-safe-left, 0px));
   background:
     radial-gradient(circle at 18% 6%, rgba(255, 206, 160, 0.22), transparent 28%),
@@ -52,9 +55,23 @@
 }
 
 .topBar {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 10px;
   margin: var(--page-padding-y, 18px) 0 -2px;
 }
 
+.pageTitle {
+  min-width: 0;
+  margin: 0;
+  color: #251a1f;
+  font-size: clamp(22px, 5.185vw, 28px);
+  font-weight: 900;
+  letter-spacing: -0.03em;
+  text-align: center;
+}
+
 .userSlot {
   padding: var(--responsive-card-padding, 18px);
   border: 1px solid rgba(25, 19, 22, 0.06);

src/app/profile/profile-screen.tsx

@@ -4,7 +4,12 @@ import { Download, LogOut, MessageCircleQuestion } from "lucide-react";
 import { signOut } from "next-auth/react";
 
 import { BackButton } from "@/app/_components";
-import { MobileShell } from "@/app/_components/core";
+import {
+  AppBottomNav,
+  FavoriteEntryButton,
+  MobileShell,
+} from "@/app/_components/core";
+import { getCharacterBySlug } from "@/data/constants/character";
 import {
   resolveGlobalRouteContext,
   type GlobalReturnToValue,
@@ -13,6 +18,7 @@ import { setPendingLogoutNavigation } from "@/router/logout-navigation";
 import { useGlobalAppNavigator } from "@/router/use-global-app-navigator";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
 import { useUserDispatch, useUserState } from "@/stores/user/user-context";
+import { getCharacterRoutes } from "@/router/routes";
 
 import { ProfileWalletCard, UserHeader } from "./components";
 import { getProfileViewModel } from "./profile-view-model";
@@ -28,6 +34,8 @@ export interface ProfileScreenProps {
 export function ProfileScreen({ returnTo }: ProfileScreenProps) {
   const navigator = useGlobalAppNavigator();
   const navigation = resolveGlobalRouteContext(returnTo);
+  const character = getCharacterBySlug(navigation.characterSlug);
+  const characterRoutes = getCharacterRoutes(navigation.characterSlug);
   const user = useUserState();
   const userDispatch = useUserDispatch();
   const auth = useAuthState();
@@ -61,6 +69,11 @@ export function ProfileScreen({ returnTo }: ProfileScreenProps) {
             variant="soft"
             analyticsKey="profile.back_to_chat"
           />
+          <h1 className={styles.pageTitle}>Menu</h1>
+          <FavoriteEntryButton
+            characterSlug={navigation.characterSlug}
+            tone="light"
+          />
         </div>
 
         <section className={`${styles.userSlot} ${styles.revealOne}`}>
@@ -175,6 +188,20 @@ export function ProfileScreen({ returnTo }: ProfileScreenProps) {
             </div>
           </section>
         ) : null}
+
+        <AppBottomNav
+          activeItem="menu"
+          privateZoneLabel={
+            character?.copy.privateZoneTitle ?? "Private Zone"
+          }
+          onChatClick={() =>
+            navigator.push(navigation.splashUrl, { scroll: false })
+          }
+          onPrivateZoneClick={() =>
+            navigator.push(characterRoutes.privateZone, { scroll: false })
+          }
+          onMenuClick={() => undefined}
+        />
       </div>
     </MobileShell>
   );

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

@@ -12,7 +12,7 @@ describe("splash Tailwind components", () => {
 
     expect(html).toContain("z-2");
     expect(html).toContain("inline-flex");
-    expect(html).toContain("block h-auto w-auto");
+    expect(html).toContain("block h-auto w-[clamp(136px,38vw,158px)]");
     expect(html).toContain("%2Fimages%2Fsplash%2Fic-logo-home.png");
   });
 
@@ -30,10 +30,9 @@ describe("splash Tailwind components", () => {
   it("renders SplashContent with Tailwind typography classes", () => {
     const html = renderToStaticMarkup(<SplashContent characterName="Maya" />);
 
-    expect(html).toContain("flex flex-col gap-md");
+    expect(html).toContain("Welcome to Maya&#x27;s private world.");
+    expect(html).toContain("Just you and me.");
     expect(html).toContain("font-(family-name:--font-athelas)");
-    expect(html).toContain("whitespace-pre-line");
-    expect(html).toContain("Welcome to Maya");
   });
 
   it("renders SplashButton as an always-ready action", () => {

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

@@ -12,8 +12,10 @@ import Image from "next/image";
 
 export function SplashBackground({
   src,
+  objectPosition,
 }: {
   src: string;
+  objectPosition?: string;
 }) {
   return (
     <div className="absolute inset-0 z-0 overflow-hidden bg-splash-background">
@@ -24,6 +26,7 @@ export function SplashBackground({
         priority
         sizes="(max-width: 540px) 100vw, 540px"
         className="object-cover object-center"
+        style={{ objectPosition }}
       />
     </div>
   );

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

@@ -2,17 +2,15 @@
  * Splash 主内容文案
  */
 
-const APOSTROPHE = "'";
-
 export function SplashContent({ characterName }: { characterName: string }) {
   return (
-    <div className="z-2 flex flex-col gap-md">
+    <div className="z-2 flex flex-col gap-1.5 text-left text-white">
-      <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">
+      <h1 className="m-0 max-w-105 font-(family-name:--font-athelas) text-[clamp(29px,8.2vw,35px)] font-bold leading-[1.08] text-white [text-shadow:0_2px_18px_rgba(0,0,0,0.42)]">
-        Welcome to {characterName}{APOSTROPHE}s secret hideout~
+        Welcome to {characterName}&apos;s private world.
-        {"\n"}It{APOSTROPHE}s just the two of us now.
-        {"\n"}Feel free to whisper your
-        {"\n"}little secrets.
       </h1>
+      <p className="m-0 text-[clamp(15px,4.1vw,18px)] font-semibold leading-[1.4] text-white/92 [text-shadow:0_2px_12px_rgba(0,0,0,0.5)]">
+        Just you and me.
+      </p>
     </div>
   );
 }

src/app/splash/components/splash-latest-message.module.css

@@ -1,16 +1,15 @@
 .card {
   display: grid;
+  box-sizing: border-box;
   width: 100%;
+  height: 80px;
   grid-template-columns: auto 1fr;
   align-items: center;
-  gap: 12px;
+  gap: 10px;
-  margin-top: var(--page-section-gap-lg, 26px);
+  padding: 9px 11px;
-  padding: 12px 14px;
+  border: 1px solid rgba(255, 255, 255, 0.28);
-  border: 1px solid rgba(255, 255, 255, 0.22);
+  border-radius: 16px;
-  border-radius: 24px;
+  background: rgba(31, 22, 29, 0.48);
-  background:
-    linear-gradient(135deg, rgba(255, 255, 255, 0.24), rgba(255, 255, 255, 0.1)),
-    rgba(28, 19, 30, 0.18);
   color: #ffffff;
   cursor: pointer;
   font: inherit;
@@ -19,8 +18,8 @@
   touch-action: manipulation;
   box-shadow:
     inset 0 1px 0 rgba(255, 255, 255, 0.18),
-    0 18px 42px rgba(46, 22, 38, 0.18);
+    0 12px 30px rgba(31, 17, 27, 0.2);
-  backdrop-filter: blur(18px);
+  backdrop-filter: blur(14px);
   animation: messageFloatIn 0.5s ease 0.08s backwards;
   transition:
     border-color 0.18s ease,
@@ -53,8 +52,8 @@
 
 .avatarWrap {
   display: grid;
-  width: 48px;
+  width: 40px;
-  height: 48px;
+  height: 40px;
   place-items: center;
   border: 2px solid rgba(255, 255, 255, 0.74);
   border-radius: 9999px;
@@ -92,10 +91,15 @@
 }
 
 .message {
+  display: -webkit-box;
+  min-height: 2.6em;
+  overflow: hidden;
   color: #ffffff;
-  font-size: clamp(14px, 3.333vw, 17px);
+  font-size: clamp(13px, 3.45vw, 16px);
-  font-weight: 760;
+  font-weight: 720;
-  line-height: 1.35;
+  line-height: 1.3;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
 }
 
 .messageLoading {

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

@@ -9,7 +9,7 @@ export function SplashLogo() {
         width={180}
         height={60}
         priority
-        className="block h-auto w-auto"
+        className="block h-auto w-[clamp(136px,38vw,158px)]"
       />
     </div>
   );

src/app/splash/components/splash-screen.module.css

@@ -8,20 +8,24 @@
   overflow: hidden;
 }
 
-/* 渐变：accent (bottom-left) → transparent (center-right) */
+.imageScrim {
-.gradientOverlay {
   position: absolute;
   inset: 0;
-  background: linear-gradient(
+  background: rgba(25, 17, 23, 0.08);
-    to top right,
+  box-shadow:
-    var(--color-accent),
+    inset 0 -290px 150px -145px rgba(20, 12, 18, 0.78),
-    transparent 60%
+    inset 0 110px 90px -90px rgba(11, 8, 10, 0.42);
-  );
-  opacity: 0.5;
   z-index: 1;
   pointer-events: none;
 }
 
+.favoriteAction {
+  position: absolute;
+  top: calc(var(--page-padding-y, 20px) + var(--app-safe-top, 0px));
+  right: calc(var(--page-padding-x, 20px) + var(--app-safe-right, 0px));
+  z-index: 4;
+}
+
 .content {
   position: relative;
   z-index: 2;
@@ -42,15 +46,9 @@
   flex: 1 1 auto;
 }
 
-.buttonArea {
+.bottomStack {
-  margin-top: var(--page-section-gap-lg, 26px);
+  display: flex;
-}
+  flex-direction: column;
-
+  gap: clamp(12px, 3.6vw, 18px);
-.bottom {
+  padding-bottom: clamp(12px, 3.6vw, 18px);
-  margin: var(--page-section-gap-lg, 32px) 0 0 0;
-  font-size: var(--responsive-body, var(--font-size-md));
-  font-weight: 400;
-  line-height: 1.5;
-  color: rgba(255, 255, 255, 0.9);
-  text-align: left;
 }

src/app/splash/splash-screen.tsx

@@ -2,7 +2,13 @@
 
 import { useEffect } from "react";
 
-import { AppBottomNav, MobileShell } from "@/app/_components/core";
+import {
+  AppBottomNav,
+  FavoriteEntryButton,
+  MobileShell,
+} from "@/app/_components/core";
+import { buildGlobalPageUrl } from "@/router/global-route-context";
+import { ROUTES } from "@/router/routes";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import {
   useActiveCharacter,
@@ -45,19 +51,39 @@ export function SplashScreen() {
     navigator.push(characterRoutes.splash, { scroll: false });
   };
 
+  const handleOpenMenu = () => {
+    navigator.push(
+      buildGlobalPageUrl(ROUTES.profile, characterRoutes.chat),
+      { scroll: false },
+    );
+  };
+
   useEffect(() => {
     pwaUtil.prepareInstallPrompt();
   }, []);
 
+  const hasLatestMessage =
+    latestMessage.isLoading || Boolean(latestMessage.message);
+
   return (
     <MobileShell background="var(--color-splash-background)">
       <div className={styles.wrapper}>
-        <SplashBackground src={character.assets.cover} />
+        <SplashBackground
-        {/* 渐变叠加层：accent → transparent (bottom-left → center-right) */}
+          src={character.assets.splashCover ?? character.assets.cover}
-        <div className={styles.gradientOverlay} aria-hidden="true" />
+          objectPosition={character.id === "maya-tan" ? "52% center" : undefined}
+        />
+        <div className={styles.imageScrim} aria-hidden="true" />
+        <div className={styles.favoriteAction}>
+          <FavoriteEntryButton
+            characterSlug={character.slug}
+            tone="dark"
+          />
+        </div>
         <div className={styles.content}>
           <SplashLogo />
           <div className={styles.spacer} />
+          <div className={styles.bottomStack}>
+            {hasLatestMessage ? (
               <SplashLatestMessage
                 message={latestMessage.message}
                 characterName={character.shortName}
@@ -65,21 +91,17 @@ export function SplashScreen() {
                 isLoading={latestMessage.isLoading}
                 onOpenChat={handleStartChat}
               />
+            ) : null}
             <SplashContent characterName={character.shortName} />
-          <div className={styles.buttonArea}>
             <SplashButton onStartChat={handleStartChat} />
           </div>
-          <p className={styles.bottom}>
-            {character.displayName}, {character.tagline}
-            <br />
-            24/7 online | Chat | Companion | Heal | Sweet moments
-          </p>
         </div>
         <AppBottomNav
           activeItem="chat"
-          privateZoneLabel={character.copy.privateZoneTitle}
+          privateZoneLabel="Private Zone"
           onChatClick={handleOpenSplash}
           onPrivateZoneClick={handleOpenPrivateZone}
+          onMenuClick={handleOpenMenu}
         />
       </div>
     </MobileShell>

src/core/net/chat-websocket.ts

@@ -12,6 +12,10 @@ import { getApiConfig } from "@/core/net/config/api_config";
 import { ExceptionHandler } from "@/core/errors";
 import { AppEnvUtil } from "@/utils/app-env";
 import { Logger } from "@/utils/logger";
+import {
+  CommercialActionSchema,
+  type CommercialAction,
+} from "@/data/schemas/chat";
 
 const log = new Logger("ChatWebSocket");
 const RECONNECT_DELAY_MS = 3000;
@@ -40,6 +44,7 @@ export class ChatWebSocket {
   onVoiceReady: ((index: number, audioUrl: string) => void) | null = null;
   onImage: ((url: string) => void) | null = null;
   onPaywallStatus: ((payload: PaywallStatusPayload) => void) | null = null;
+  onCommercialAction: ((action: CommercialAction) => void) | null = null;
   onError: ((errorMessage: string) => void) | null = null;
 
   constructor(
@@ -140,6 +145,12 @@ export class ChatWebSocket {
           url?: string | null;
         };
         lockDetail?: Partial<PaywallStatusPayload>;
+        actionId?: string;
+        type?: string;
+        copy?: string;
+        ctaLabel?: string;
+        target?: string;
+        ruleId?: string;
       };
     };
     try {
@@ -179,6 +190,11 @@ export class ChatWebSocket {
         });
         break;
       }
+      case "commercial_action": {
+        const action = CommercialActionSchema.safeParse(payload.data);
+        if (action.success) this.onCommercialAction?.(action.data);
+        break;
+      }
       case "error":
         this.onError?.(payload.error ?? "Unknown error");
         break;

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

@@ -90,6 +90,9 @@ describe("local character catalog", () => {
 
   it("resolves characters by id and normalized slug", () => {
     expect(getCharacterById("maya-tan")?.displayName).toBe("Maya Tan");
+    expect(getCharacterById("maya-tan")?.assets.splashCover).toBe(
+      "/images/cover/maya-home.webp",
+    );
     expect(getCharacterBySlug(" NAYELI ")?.displayName).toBe(
       "Nayeli Cervantes",
     );

src/data/constants/character.ts

@@ -16,6 +16,7 @@ export interface CharacterProfile {
   readonly assets: {
     readonly avatar: string;
     readonly cover: string;
+    readonly splashCover?: string;
     readonly chatBackground: string;
     readonly privateZoneBanner: string;
   };
@@ -97,6 +98,7 @@ const CHARACTER_PROFILES: readonly CharacterProfile[] = Object.freeze([
     assets: {
       avatar: "/images/avatar/maya.png",
       cover: "/images/cover/maya.webp",
+      splashCover: "/images/cover/maya-home.webp",
       chatBackground: "/images/chat/bg-chatpage.png",
       privateZoneBanner: "/images/private-zone/banner/maya.png",
     },

src/data/repositories/chat_remote_data_source.ts

@@ -7,6 +7,8 @@ import {
   ChatHistoryResponse,
   ChatPreviewsResponse,
   ChatSendResponse,
+  OpeningMessageRequestSchema,
+  OpeningMessageResponse,
   SendMessageRequestSchema,
   UnlockHistoryRequestSchema,
   UnlockHistoryResponse,
@@ -50,6 +52,19 @@ export class ChatRemoteDataSource {
     });
   }
 
+  async saveOpeningMessage(
+    characterId: string,
+    openingMessage: string,
+    options?: ChatRequestOptions,
+  ): Promise<Result<OpeningMessageResponse>> {
+    return Result.wrap(() =>
+      this.api.saveOpeningMessage(
+        OpeningMessageRequestSchema.parse({ characterId, openingMessage }),
+        options,
+      ),
+    );
+  }
+
   async getPreviews(
     options?: ChatRequestOptions,
   ): Promise<Result<ChatPreviewsResponse>> {

src/data/repositories/chat_repository.ts

@@ -12,6 +12,7 @@ import type {
   ChatPreviewsResponse,
   ChatMessage,
   ChatSendResponse,
+  OpeningMessageResponse,
   UnlockHistoryResponse,
   UnlockPrivateResponse,
 } from "@/data/schemas/chat";
@@ -46,6 +47,18 @@ export class ChatRepository implements IChatRepository {
     return this.remote.sendMessage(characterId, message, options);
   }
 
+  async saveOpeningMessage(
+    characterId: string,
+    openingMessage: string,
+    options?: ChatRequestOptions,
+  ): Promise<Result<OpeningMessageResponse>> {
+    return this.remote.saveOpeningMessage(
+      characterId,
+      openingMessage,
+      options,
+    );
+  }
+
   /** 获取聊天历史，分页参数默认 limit=50, offset=0。 */
   async getHistory(
     characterId: string,

src/data/repositories/interfaces/ichat_repository.ts

@@ -13,6 +13,7 @@ import type {
   ChatMediaKind,
   ChatMessage,
   ChatSendResponse,
+  OpeningMessageResponse,
   UnlockHistoryResponse,
   UnlockPrivateResponse,
 } from "@/data/schemas/chat";
@@ -65,6 +66,13 @@ export interface IChatRepository {
     options?: ChatSendOptions,
   ): Promise<Result<ChatSendResponse>>;
 
+  /** 幂等保存角色首次开场白。 */
+  saveOpeningMessage(
+    characterId: string,
+    openingMessage: string,
+    options?: ChatRequestOptions,
+  ): Promise<Result<OpeningMessageResponse>>;
+
   /** 获取聊天历史，分页参数默认 limit=50, offset=0。 */
   getHistory(
     characterId: string,

src/data/schemas/chat/index.ts

@@ -5,6 +5,7 @@
 export * from "./chat_lock_type";
 export * from "./chat_media";
 export * from "./chat_message";
+export * from "./opening_message";
 export * from "./chat_payloads";
 export * from "./request/send_message_request";
 export * from "./request/unlock_history_request";

src/data/schemas/chat/opening_message.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+export const OpeningMessageRequestSchema = z
+  .object({
+    characterId: z.string().min(1).max(100),
+    openingMessage: z.string().min(1).max(1000),
+  })
+  .readonly();
+
+export const OpeningMessageResponseSchema = z
+  .object({
+    messageId: z.string().min(1),
+    created: z.boolean(),
+    openingMessage: z.string().min(1),
+    createdAt: z.string().min(1),
+  })
+  .readonly();
+
+export type OpeningMessageRequest = z.output<
+  typeof OpeningMessageRequestSchema
+>;
+export type OpeningMessageResponse = z.output<
+  typeof OpeningMessageResponseSchema
+>;

src/data/schemas/chat/response/chat_send_response.ts

@@ -12,6 +12,19 @@ import {
 } from "../../nullable-defaults";
 import { ChatImageSchema, ChatLockDetailSchema } from "../chat_payloads";
 
+export const CommercialActionSchema = z
+  .object({
+    actionId: z.string().min(1),
+    type: z.enum(["giftOffer", "privateAlbumOffer"]),
+    copy: z.string().min(1),
+    ctaLabel: z.string().min(1),
+    target: z.enum(["giftCatalog", "privateZone"]),
+    ruleId: z.string().min(1),
+  })
+  .readonly();
+
+export type CommercialAction = z.output<typeof CommercialActionSchema>;
+
 export const ChatSendResponseSchema = z
   .object({
     reply: stringOrEmpty,
@@ -27,6 +40,7 @@ export const ChatSendResponseSchema = z
     creditsCharged: numberOrZero,
     requiredCredits: numberOrZero,
     shortfallCredits: numberOrZero,
+    commercialAction: CommercialActionSchema.nullish().default(null),
   })
   .readonly();
 

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

@@ -60,6 +60,34 @@ describe("multi-character API contract", () => {
     });
   });
 
+  it("persists the character opening message with the canonical contract", async () => {
+    httpClientMock.mockResolvedValue({
+      success: true,
+      data: {
+        messageId: "opening-message-1",
+        created: true,
+        openingMessage: "Hello from Elio",
+        createdAt: "2026-07-23T00:00:00Z",
+      },
+    });
+
+    await new ChatApi().saveOpeningMessage({
+      characterId: CHARACTER_ID,
+      openingMessage: "Hello from Elio",
+    });
+
+    expect(httpClientMock).toHaveBeenCalledWith(
+      "/api/chat/opening-message",
+      {
+        method: "POST",
+        body: {
+          characterId: CHARACTER_ID,
+          openingMessage: "Hello from Elio",
+        },
+      },
+    );
+  });
+
   it("loads the chat character catalog", async () => {
     httpClientMock.mockResolvedValue({
       success: true,

src/data/services/api/api_contract.json

@@ -18,6 +18,7 @@
   "paymentGiftProducts": { "method": "get", "path": "/api/payment/gift-products" },
   "paymentTipMessage": { "method": "post", "path": "/api/payment/tip-message" },
   "chatSend": { "method": "post", "path": "/api/chat/send" },
+  "chatOpeningMessage": { "method": "post", "path": "/api/chat/opening-message" },
   "chatHistory": { "method": "get", "path": "/api/chat/history" },
   "chatUnlockPrivate": { "method": "post", "path": "/api/chat/unlock-private" },
   "chatUnlockHistory": { "method": "post", "path": "/api/chat/unlock-history" },

src/data/services/api/api_path.ts

@@ -70,6 +70,9 @@ export class ApiPath {
   /** 发送消息 */
   static readonly chatSend = apiContract.chatSend.path;
 
+  /** 幂等保存角色开场白 */
+  static readonly chatOpeningMessage = apiContract.chatOpeningMessage.path;
+
   /** 获取聊天历史 */
   static readonly chatHistory = apiContract.chatHistory.path;
 

src/data/services/api/chat_api.ts

@@ -11,6 +11,9 @@ import {
   ChatPreviewsResponseSchema,
   ChatSendResponse,
   ChatSendResponseSchema,
+  OpeningMessageRequest,
+  OpeningMessageResponse,
+  OpeningMessageResponseSchema,
   SendMessageRequest,
   UnlockHistoryRequest,
   UnlockHistoryResponse,
@@ -39,6 +42,22 @@ export class ChatApi {
     return ChatSendResponseSchema.parse(unwrap(env) as Record<string, unknown>);
   }
 
+  /** 幂等保存当前角色的首次开场白。 */
+  async saveOpeningMessage(
+    body: OpeningMessageRequest,
+    options?: { signal?: AbortSignal },
+  ): Promise<OpeningMessageResponse> {
+    const env = await httpClient<ApiEnvelope<unknown>>(
+      ApiPath.chatOpeningMessage,
+      {
+        method: "POST",
+        body,
+        ...(options?.signal ? { signal: options.signal } : {}),
+      },
+    );
+    return OpeningMessageResponseSchema.parse(unwrap(env));
+  }
+
   /**
    * 获取聊天历史
    */

src/lib/chat/chat_external_browser.ts

@@ -5,7 +5,13 @@ import { UserStorage } from "@/data/storage/user/user_storage";
 import { ROUTES } from "@/router/routes";
 import { UrlLauncherUtil } from "@/utils/url-launcher-util";
 
-export async function openChatInExternalBrowser(): Promise<void> {
+export interface OpenChatInExternalBrowserInput {
+  characterSlug?: string;
+}
+
+export async function openChatInExternalBrowser({
+  characterSlug,
+}: OpenChatInExternalBrowserInput = {}): Promise<void> {
   const authStorage = AuthStorage.getInstance();
   const userStorage = UserStorage.getInstance();
   const [deviceIdR, asidR, psidR, avatarUrlR] =
@@ -21,18 +27,15 @@ export async function openChatInExternalBrowser(): Promise<void> {
   const psid = psidR.success ? psidR.data : null;
   const avatarUrl = avatarUrlR.success ? avatarUrlR.data : null;
 
-  if (deviceId && asid) {
   UrlLauncherUtil.openUrlWithExternalBrowser(ROUTES.externalEntry, {
     queryParams: {
       target: "chat",
-        device_id: deviceId,
+      favorite: "1",
-        asid,
+      ...(characterSlug ? { character: characterSlug } : {}),
+      ...(deviceId ? { device_id: deviceId } : {}),
+      ...(asid ? { asid } : {}),
       ...(psid ? { psid } : {}),
       ...(avatarUrl ? { avatar_url: avatarUrl } : {}),
     },
   });
-    return;
-  }
-
-  UrlLauncherUtil.openUrlWithExternalBrowser(ROUTES.splash);
 }

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

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  isFavoriteEntryRequest,
+  resolveFavoriteEntryMode,
+} from "../favorite_entry";
+
+describe("favorite external entry", () => {
+  it("keeps the favorite action inside an in-app browser", () => {
+    expect(
+      resolveFavoriteEntryMode({
+        hasFavoriteIntent: true,
+        isAndroid: true,
+        isIOS: false,
+        isInAppBrowser: true,
+        isInstalled: false,
+      }),
+    ).toBe("favorite");
+  });
+
+  it("turns the external Android action into Download", () => {
+    expect(
+      resolveFavoriteEntryMode({
+        hasFavoriteIntent: true,
+        isAndroid: true,
+        isIOS: false,
+        isInAppBrowser: false,
+        isInstalled: false,
+      }),
+    ).toBe("download");
+  });
+
+  it("turns the external iOS action into Saved", () => {
+    expect(
+      resolveFavoriteEntryMode({
+        hasFavoriteIntent: true,
+        isAndroid: false,
+        isIOS: true,
+        isInAppBrowser: false,
+        isInstalled: false,
+      }),
+    ).toBe("saved");
+  });
+
+  it("treats an installed PWA as saved", () => {
+    expect(
+      resolveFavoriteEntryMode({
+        hasFavoriteIntent: false,
+        isAndroid: true,
+        isIOS: false,
+        isInAppBrowser: false,
+        isInstalled: true,
+      }),
+    ).toBe("saved");
+  });
+
+  it("accepts only the explicit favorite entry marker", () => {
+    expect(isFavoriteEntryRequest("1")).toBe(true);
+    expect(isFavoriteEntryRequest("true")).toBe(false);
+    expect(isFavoriteEntryRequest(null)).toBe(false);
+  });
+});

src/lib/navigation/favorite_entry.ts

@@ -0,0 +1,51 @@
+"use client";
+
+export const FAVORITE_ENTRY_QUERY_PARAM = "favorite";
+export const FAVORITE_ENTRY_QUERY_VALUE = "1";
+
+const FAVORITE_ENTRY_STORAGE_KEY = "cozsweet:favorite_entry";
+
+export type FavoriteEntryMode = "favorite" | "download" | "saved";
+
+export interface FavoriteEntryModeInput {
+  hasFavoriteIntent: boolean;
+  isAndroid: boolean;
+  isIOS: boolean;
+  isInAppBrowser: boolean;
+  isInstalled: boolean;
+}
+
+export function resolveFavoriteEntryMode({
+  hasFavoriteIntent,
+  isAndroid,
+  isIOS,
+  isInAppBrowser,
+  isInstalled,
+}: FavoriteEntryModeInput): FavoriteEntryMode {
+  if (isInAppBrowser) return "favorite";
+  if (isInstalled) return "saved";
+  if (!hasFavoriteIntent) return "favorite";
+  if (isAndroid) return "download";
+  if (isIOS) return "saved";
+  return "saved";
+}
+
+export function isFavoriteEntryRequest(value?: string | null): boolean {
+  return value?.trim() === FAVORITE_ENTRY_QUERY_VALUE;
+}
+
+export function persistFavoriteEntryIntent(): void {
+  if (typeof window === "undefined") return;
+  window.localStorage.setItem(
+    FAVORITE_ENTRY_STORAGE_KEY,
+    FAVORITE_ENTRY_QUERY_VALUE,
+  );
+}
+
+export function hasPersistedFavoriteEntryIntent(): boolean {
+  if (typeof window === "undefined") return false;
+  return (
+    window.localStorage.getItem(FAVORITE_ENTRY_STORAGE_KEY) ===
+    FAVORITE_ENTRY_QUERY_VALUE
+  );
+}

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

@@ -72,6 +72,30 @@ function makeChatState(overrides: Partial<ChatState> = {}): ChatState {
 }
 
 describe("sendResponseToUiMessage", () => {
+  it("keeps a typed commercial action on the assistant message", () => {
+    const message = sendResponseToUiMessage(
+      makeResponse({
+        commercialAction: {
+          actionId: "action-1",
+          type: "giftOffer",
+          copy: "Buy me a coffee?",
+          ctaLabel: "View gifts",
+          target: "giftCatalog",
+          ruleId: "coffee_support_question",
+        },
+      }),
+    );
+
+    expect(message.commercialAction).toEqual({
+      actionId: "action-1",
+      type: "giftOffer",
+      copy: "Buy me a coffee?",
+      ctaLabel: "View gifts",
+      target: "giftCatalog",
+      ruleId: "coffee_support_question",
+    });
+  });
+
   it("maps locked voice messages without treating them as private text", () => {
     const message = sendResponseToUiMessage(
       makeResponse({

src/stores/chat/__tests__/chat-opening-history-sync.test.ts

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const repository = vi.hoisted(() => ({
+  saveOpeningMessage: vi.fn(),
+  getHistory: vi.fn(),
+  saveMessagesToLocal: vi.fn(),
+  prefetchMediaForMessages: vi.fn(),
+}));
+
+vi.mock("@/data/repositories/chat_repository_loader", () => ({
+  loadChatRepository: vi.fn(async () => repository),
+}));
+
+import { syncNetworkHistory } from "@/stores/chat/chat-history-sync";
+
+describe("chat opening-message history sync", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    repository.saveOpeningMessage.mockResolvedValue({
+      success: true,
+      data: {
+        messageId: "opening-1",
+        created: true,
+        openingMessage: "Hello from Elio",
+        createdAt: "2026-07-23T00:00:00Z",
+      },
+    });
+    repository.getHistory.mockResolvedValue({
+      success: true,
+      data: {
+        messages: [
+          {
+            id: "opening-1",
+            role: "assistant",
+            type: "text",
+            content: "Hello from Elio",
+            createdAt: "2026-07-23T00:00:00Z",
+            audioUrl: null,
+            image: { type: null, url: null },
+            lockDetail: { locked: false, reason: null },
+          },
+        ],
+        total: 1,
+        limit: 50,
+        offset: 0,
+      },
+    });
+    repository.saveMessagesToLocal.mockResolvedValue({
+      success: true,
+      data: undefined,
+    });
+    repository.prefetchMediaForMessages.mockResolvedValue({
+      success: true,
+      data: undefined,
+    });
+  });
+
+  it("persists the greeting before loading authoritative history", async () => {
+    const output = await syncNetworkHistory(
+      "elio",
+      0,
+      [],
+      "user:test::character:elio",
+      "Hello from Elio",
+    );
+
+    expect(repository.saveOpeningMessage).toHaveBeenCalledWith(
+      "elio",
+      "Hello from Elio",
+      { signal: undefined },
+    );
+    expect(repository.saveOpeningMessage.mock.invocationCallOrder[0]).toBeLessThan(
+      repository.getHistory.mock.invocationCallOrder[0] ?? Number.MAX_SAFE_INTEGER,
+    );
+    expect(output?.messages).toMatchObject([
+      {
+        remoteId: "opening-1",
+        content: "Hello from Elio",
+      },
+    ]);
+    expect(output?.messages[0]?.isSynthetic).toBeUndefined();
+  });
+});

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

@@ -101,6 +101,20 @@ export async function syncNetworkHistory(
     emptyChatGreeting,
   );
 
+  const openingResult = await chatRepo.saveOpeningMessage(
+    characterId,
+    emptyChatGreeting,
+    { signal },
+  );
+  if (Result.isErr(openingResult)) {
+    if (isAbortError(openingResult.error)) throw openingResult.error;
+    log.warn("[chat-machine] opening message persistence skipped", {
+      characterId,
+      error: openingResult.error,
+    });
+  }
+  signal?.throwIfAborted();
+
   const networkResult = await chatRepo.getHistory(
     characterId,
     CHAT_HISTORY_LIMIT,

src/stores/chat/helper/message-mappers.ts

@@ -74,6 +74,9 @@ export function sendResponseToUiMessage(response: ChatSendResponse): UiMessage {
     ...(response.audioUrl && !response.lockDetail.locked
       ? { audioUrl: response.audioUrl }
       : {}),
+    ...(response.commercialAction
+      ? { commercialAction: response.commercialAction }
+      : {}),
     ...deriveUiLockFields(response.lockDetail, response.image.url),
   };
 }

src/stores/chat/ui-message.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CommercialActionSchema } from "@/data/schemas/chat";
 
 export const UiMessageSchema = z.object({
   displayId: z.string().min(1),
@@ -16,6 +17,7 @@ export const UiMessageSchema = z.object({
   isPrivate: z.boolean().nullable().optional(),
   lockedPrivate: z.boolean().nullable().optional(),
   privateMessageHint: z.string().nullable().optional(),
+  commercialAction: CommercialActionSchema.nullable().optional(),
 });
 
 export type UiMessage = z.infer<typeof UiMessageSchema>;