feat(mobile): improve image viewer and install entry

(cherry picked from commit 556bfd2919)

.gitea/workflows/docker-image.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - main
-      - test
+      - pre
   workflow_dispatch:
 
 jobs:
@@ -48,7 +48,7 @@ jobs:
               DEPLOY_ENV="prod"
               NEXT_ENV_FILE=".env.production"
               ;;
-            test)
+            pre)
               DEPLOY_ENV="test"
               NEXT_ENV_FILE=".env.local"
               ;;

.githooks/post-receive

@@ -72,12 +72,12 @@ copy_env_by_branch() {
             START_PORT=9185
             echo "=== env: copied .env.production (main → prod) ===" >> "$LOG_FILE"
             ;;
-        test)
+        pre)
             cp -f env-example/.env.local.example .env.local
             ENV_FILE=".env.local"
             DEPLOY_ENV="test"
             START_PORT=9135
-            echo "=== env: copied .env.local (test → test) ===" >> "$LOG_FILE"
+            echo "=== env: copied .env.local (pre branch → test runtime) ===" >> "$LOG_FILE"
             ;;
         dev)
             cp -f env-example/.env.development.example .env.local

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 ./

barrelsby.json

@@ -25,9 +25,9 @@
     "./src/data/schemas/payment",
     "./src/data/schemas/payment/request",
     "./src/data/schemas/payment/response",
-    "./src/data/schemas/private-zoom",
+    "./src/data/schemas/private-zone",
-    "./src/data/schemas/private-zoom/request",
+    "./src/data/schemas/private-zone/request",
-    "./src/data/schemas/private-zoom/response",
+    "./src/data/schemas/private-zone/response",
     "./src/data/schemas/user",
     "./src/data/storage/app",
     "./src/data/storage/auth",

docs/auto-build-restart.md

@@ -12,7 +12,7 @@
 
 | 环境 | Git remote | 推送分支 | 宿主机端口 | 容器端口 | 部署脚本 |
 | --- | --- | --- | --- | --- | --- |
-| 测试环境 | `test` | `test` | `9135` | `3000` | `scripts/deploy/deploy_web_test.sh` |
+| 预发环境 | `test` | `pre` | `9135` | `3000` | `scripts/deploy/deploy_web_test.sh` |
 | 生产环境 | `production` | `main` | `9185` | `3000` | `scripts/deploy/deploy_web.sh` |
 
 当前 remote 配置示例：
@@ -26,15 +26,15 @@ production root@43.106.13.130:/root/cozsweet-repos/main
 
 ## 本地发布流程
 
-旧测试环境发布流程（脚本迁移前）：
+旧预发环境发布流程（脚本迁移前）：
 
-1. 进入 test worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test`
+1. 进入 pre worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre`
 2. 确认当前分支。
-3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `test` 分支。
+3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `pre` 分支。
 4. 复制测试环境图标到 `public/`。
 5. 复制 `env-example/.env.local.example` 到 `.env.local`。
 6. 执行旧版 `scripts/deploy/deploy_web_test.sh`。
-7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `test` 分支。
+7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `pre` 分支。
 8. 推送成功后尝试清除 Cloudflare CDN 缓存。
 
 旧生产环境发布流程（脚本迁移前）：
@@ -71,7 +71,7 @@ production root@43.106.13.130:/root/cozsweet-repos/main
 | 服务端分支 | 环境变量复制 | 宿主机端口 | 容器名 | 镜像标签 |
 | --- | --- | --- | --- | --- |
 | `main` | `env-example/.env.production.example` → `.env.production` | `9185` | `cozsweet-web-prod` | `cozsweet-web:prod-<commit>` |
-| `test` | `env-example/.env.local.example` → `.env.local` | `9135` | `cozsweet-web-test` | `cozsweet-web:test-<commit>` |
+| `pre` | `env-example/.env.local.example` → `.env.local` | `9135` | `cozsweet-web-test` | `cozsweet-web:test-<commit>` |
 | `dev` | `env-example/.env.development.example` → `.env.local` | `9135` | `cozsweet-web-dev` | `cozsweet-web:dev-<commit>` |
 | 其他分支 | 使用默认 `.env.local` | `9135` | `cozsweet-web-<branch>` | `cozsweet-web:<branch>-<commit>` |
 
@@ -264,12 +264,12 @@ ABORTED ... (docker compose up failed)
 
 1. `scripts/deploy/*` 只负责推送代码，不负责本地构建和本地启动。
 2. 自动构建和自动重启只发生在服务器端 `post-receive` hook。
-3. `main` 分支对应生产环境，`test` 分支对应测试环境。
+3. `main` 分支对应生产环境，`pre` 分支对应预发环境。
 4. 生产推送当前使用 `git push --force production main`。
 5. 构建失败时不会重启容器，旧容器继续运行。
 6. 服务启动由 Docker Compose 管理，不再使用 `nohup pnpm run start`。
 7. 服务器需要安装 Docker，并支持 `docker compose` 或旧版 `docker-compose` 命令。
-8. 测试环境和生产环境都通过同一套 `post-receive` 容器化流程部署，差异仅由分支、环境变量文件和端口决定。
+8. 预发环境和生产环境都通过同一套 `post-receive` 容器化流程部署，差异仅由分支、环境变量文件和端口决定。
 
 ## 后续优化建议
 

docs/backend/FRONTEND_MULTI_ROLE_CHAT_API.md

@@ -63,7 +63,7 @@ Authorization: Bearer <TOKEN>
 2. `isActive=true`；
 3. `capabilities.chat=true`。
 
-服务端目录决定角色是否可聊天及排序；本地目录继续提供 slug、图片、文案和 Tip 能力。`privateZoom` 只有在本地能力和服务端 `privateContent` 同时开启时可用。
+服务端目录决定角色是否可聊天及排序；本地目录继续提供 slug、图片、文案和 Tip 能力。`privateZone` 只有在本地能力和服务端 `privateContent` 同时开启时可用。
 
 远端目录返回前，生产环境只使用 Elio 作为临时目录；非生产环境可使用完整本地目录。远端目录加载成功后，以合并结果为准。
 
@@ -72,7 +72,7 @@ Authorization: Bearer <TOKEN>
 ```text
 /characters/{slug}/splash
 /characters/{slug}/chat
-/characters/{slug}/private-zoom
+/characters/{slug}/private-zone
 /characters/{slug}/tip
 ```
 
@@ -81,11 +81,11 @@ Authorization: Bearer <TOKEN>
 ```text
 /splash       -> /characters/elio/splash
 /chat         -> /characters/elio/chat
-/private-zoom -> /characters/elio/private-zoom
+/private-zone -> /characters/elio/private-zone
 /tip          -> /characters/elio/tip
 ```
 
-Chat Provider 以 `characterId` 为边界，路由角色变化时创建新的 Actor。Private Zoom 的角色边界由 [Private Zoom 权威协议](./FRONTEND_PRIVATE_ZOOM_API.md) 定义。
+Chat Provider 以 `characterId` 为边界，路由角色变化时创建新的 Actor。Private Zone 的角色边界由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
 
 ## 3. Chat HTTP 协议
 
@@ -308,7 +308,7 @@ conversationKey = {ownerKey}::character:{encodeURIComponent(characterId)}
 
 ## 7. 关联业务边界
 
-- Private Zoom 的相册、解锁、Gallery 和支付回跳由 [Private Zoom 权威协议](./FRONTEND_PRIVATE_ZOOM_API.md) 定义。
+- Private Zone 的相册、解锁、Gallery 和支付回跳由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
 - Tip 的角色归属、订单轮询和支付回跳由 [Payment 权威协议](./FRONTEND_PAYMENT_API.md) 定义；Chat 只保存解锁所需的原角色回跳地址。
 - 登录、支付和解锁回跳保存原角色动态 URL，不能降级为通用 `/chat`。
 - Analytics 可以使用 `characterId`，聊天正文不属于路由或身份协议的一部分。

docs/backend/FRONTEND_PAYMENT_API.md

@@ -224,7 +224,7 @@ payChannel = ezpay
 subscriptionType = vip | topup | tip
 giftCategory（仅 Tip，可空）
 giftPlanId（仅 Tip，可空）
-returnTo = chat | private-zoom | profile（可选）
+returnTo = chat | private-zone | profile（可选）
 characterSlug（可选）
 createdAt
 ```
@@ -238,7 +238,7 @@ Tip          -> /characters/{slug}/tip?category=...&planId=...&payChannel=ezpay&
 
 恢复页面只接受与当前 `paymentType` 相同的待处理订单。带有 `paymentReturn=1` 时派发 `PaymentReturned` 并继续轮询；普通进入支付页时会清理同类型的旧待处理订单。订单进入 paid、failed 或 expired 后清理持久化记录。缺少 Gift 字段的旧记录由最新目录默认选择第一件商品，不再读取 `coffee_type`。
 
-无效或未知 `characterSlug` 回退到默认角色 slug。有效角色回跳必须保留原角色，不能统一返回 Elio。`returnTo=private-zoom` 的最终页面行为由 [Private Zoom 权威协议](./FRONTEND_PRIVATE_ZOOM_API.md) 定义。
+无效或未知 `characterSlug` 回退到默认角色 slug。有效角色回跳必须保留原角色，不能统一返回 Elio。`returnTo=private-zone` 的最终页面行为由 [Private Zone 权威协议](./FRONTEND_PRIVATE_ZONE_API.md) 定义。
 
 ## 8. 成功后的跨域同步
 

docs/backend/FRONTEND_PRIVATE_ZONE_API.md

@@ -1,4 +1,4 @@
-# CozSweet Private Zoom 权威协议
+# CozSweet Private Zone 权威协议
 
 ## 1. 状态与范围
 
@@ -9,11 +9,11 @@
 | 边界 | 实现位置 |
 | --- | --- |
 | API 路径与方法 | `src/data/services/api/api_contract.json` |
-| 请求与响应字段 | `src/data/schemas/private-zoom` |
+| 请求与响应字段 | `src/data/schemas/private-zone` |
-| API 与 Repository | `src/data/services/api/private_zoom_api.ts`、`src/data/repositories/private_zoom_repository.ts` |
+| API 与 Repository | `src/data/services/api/private_zone_api.ts`、`src/data/repositories/private_zone_repository.ts` |
-| Private Zoom 状态机 | `src/stores/private-zoom` |
+| Private Zone 状态机 | `src/stores/private-zone` |
-| 页面、Gallery 与导航 | `src/app/private-zoom` |
+| 页面、Gallery 与导航 | `src/app/private-zone` |
-| 角色 Provider | `src/providers/private-zoom-route-provider.tsx` |
+| 角色 Provider | `src/providers/private-zone-route-provider.tsx` |
 
 修改上述实现时必须在同一变更中更新本文，不能再新增按相册列表、解锁或 Gallery 拆分的并行协议。
 
@@ -22,13 +22,13 @@
 标准路由：
 
 ```text
-/characters/{characterSlug}/private-zoom
+/characters/{characterSlug}/private-zone
 ```
 
 旧地址保留为默认角色重定向，并保留查询参数：
 
 ```text
-/private-zoom -> /characters/elio/private-zoom
+/private-zone -> /characters/elio/private-zone
 ```
 
 URL 使用角色 `slug`，API 和 Actor 使用角色业务 `id`：
@@ -39,14 +39,14 @@ URL 使用角色 `slug`，API 和 Actor 使用角色业务 `id`：
 | `maya-tan` | `maya` |
 | `nayeli-cervantes` | `nayeli` |
 
-角色必须同时存在于本地目录且 `capabilities.privateZoom=true`。该能力由本地配置和角色目录响应的 `privateContent` 共同决定；能力关闭或 slug 未知时路由返回 Not Found。
+角色必须同时存在于本地目录且 `capabilities.privateZone=true`。该能力由本地配置和角色目录响应的 `privateContent` 共同决定；能力关闭或 slug 未知时路由返回 Not Found。
 
-`PrivateZoomProvider` 以 `characterId` 为输入和 React key。切换角色会销毁旧 Actor 并创建空状态，不能复用上一角色的相册、余额或解锁请求。
+`PrivateZoneProvider` 以 `characterId` 为输入和 React key。切换角色会销毁旧 Actor 并创建空状态，不能复用上一角色的相册、余额或解锁请求。
 
 ## 3. 相册列表
 
 ```http
-GET <API_BASE_URL>/api/private-zoom/albums?characterId=maya-tan&limit=20
+GET <API_BASE_URL>/api/private-zone/albums?characterId=maya-tan&limit=20
 Authorization: Bearer <TOKEN>
 ```
 
@@ -55,7 +55,7 @@ Authorization: Bearer <TOKEN>
 | `characterId` | 是 | 当前角色业务 ID |
 | `limit` | 否 | 当前固定为 20 |
 
-前端当前只加载第一页，不实现 Private Zoom 分页，也不把相册列表写入本地缓存。初始化、手动刷新或登录身份变化时重新请求网络。
+前端当前只加载第一页，不实现 Private Zone 分页，也不把相册列表写入本地缓存。初始化、手动刷新或登录身份变化时重新请求网络。
 
 标准响应数据：
 
@@ -105,7 +105,7 @@ album.locked || !album.unlocked || album.lockDetail.locked
 用户点击锁定相册后，前端先展示确认 Dialog。只有待确认 `albumId` 仍存在于当前 Actor 的 `items` 中，才会发起请求。
 
 ```http
-POST <API_BASE_URL>/api/private-zoom/albums/{albumId}/unlock
+POST <API_BASE_URL>/api/private-zone/albums/{albumId}/unlock
 Content-Type: application/json
 Authorization: Bearer <TOKEN>
 ```
@@ -177,25 +177,25 @@ Schema 同时允许未知字符串，未知失败原因使用通用错误文案
 
 ## 5. 身份与支付导航
 
-Private Zoom 初始化会复用 Guest 登录引导。Auth 尚未初始化或正在加载时不请求列表；`notLoggedIn` 完成 Guest bootstrap 后再进入列表加载。Guest 和正式用户都可以读取后端允许的相册列表。
+Private Zone 初始化会复用 Guest 登录引导。Auth 尚未初始化或正在加载时不请求列表；`notLoggedIn` 完成 Guest bootstrap 后再进入列表加载。Guest 和正式用户都可以读取后端允许的相册列表。
 
 积分不足生成 Paywall 请求后：
 
 | 当前身份 | 导航 |
 | --- | --- |
-| Guest 或 Not Logged In | 打开 Auth，redirect 为当前角色 Private Zoom |
+| Guest 或 Not Logged In | 打开 Auth，redirect 为当前角色 Private Zone |
-| 已认证用户 | 打开 Top-up，`returnTo=private-zoom`，保留当前角色来源 |
+| 已认证用户 | 打开 Top-up，`returnTo=private-zone`，保留当前角色来源 |
 
 Paywall 导航发起后立即消费当前请求，避免 React 重渲染重复导航。支付回跳和订单恢复遵循 [Payment 权威协议](./FRONTEND_PAYMENT_API.md)。
 
-解锁成功后 `unlockSuccessNonce` 递增，页面桥接到 `UserFetch`，刷新当前积分和权益。Private Zoom 不自行修改 User Store 余额。
+解锁成功后 `unlockSuccessNonce` 递增，页面桥接到 `UserFetch`，刷新当前积分和权益。Private Zone 不自行修改 User Store 余额。
 
 ## 6. Gallery URL 协议
 
 解锁相册使用查询参数打开页内 Gallery：
 
 ```text
-/characters/{slug}/private-zoom?album={albumId}&image={zeroBasedIndex}
+/characters/{slug}/private-zone?album={albumId}&image={zeroBasedIndex}
 ```
 
 解析规则：
@@ -208,7 +208,7 @@ Paywall 导航发起后立即消费当前请求，避免 React 重渲染重复
 
 任一条件不满足时，页面通过 replace 删除 `album` 和 `image`，并保留其他查询参数。
 
-页面内点击九宫格缩略图时，Gallery 从该图片的后端数组原始索引打开。关闭操作优先使用浏览器 back；直接刷新或外部分享 Gallery URL 时，关闭操作使用 replace 返回当前角色 Private Zoom。
+页面内点击九宫格缩略图时，Gallery 从该图片的后端数组原始索引打开。关闭操作优先使用浏览器 back；直接刷新或外部分享 Gallery URL 时，关闭操作使用 replace 返回当前角色 Private Zone。
 
 Gallery 只浏览 `locked=false` 且 URL 非空的图片，但 URL 中的 `image` 仍使用原始数组索引。横向拖动时图片跟随指针，达到视口宽度 18%（最低 56px），或达到 0.45px/ms 且至少移动 24px 时切换；首尾越界拖动使用 0.28 阻尼且不循环。松手后使用 240ms 横向吸附动画，键盘方向键和左右按钮复用相同切换逻辑。Escape 关闭；`prefers-reduced-motion` 下取消吸附过渡。
 
@@ -222,17 +222,17 @@ Gallery 只浏览 `locked=false` 且 URL 非空的图片，但 URL 中的 `image
 - 超过 9 张时卡片显示前九张，末格显示 `+N`，Gallery 仍可浏览全部有效图片；
 - Gallery 只挂载当前图片和相邻图片，避免多图相册同时解码全部原图；
 - `creditBalance` 是当前列表/解锁响应快照，不替代 User Store 权益；
-- Private Zoom 不使用 Chat 的 `conversationKey`、消息缓存或媒体缓存；
+- Private Zone 不使用 Chat 的 `conversationKey`、消息缓存或媒体缓存；
-- Private Zoom 不持有 Payment Actor，Top-up 通过路由级导航进入独立 Payment Provider。
+- Private Zone 不持有 Payment Actor，Top-up 通过路由级导航进入独立 Payment Provider。
 
 ## 8. 变更验收
 
-Private Zoom 协议相关变更至少验证：
+Private Zone 协议相关变更至少验证：
 
-1. `src/data/schemas/private-zoom/__tests__`；
+1. `src/data/schemas/private-zone/__tests__`；
-2. `src/data/services/api/__tests__/multi_character_api.test.ts` 中的 Private Zoom 请求；
+2. `src/data/services/api/__tests__/multi_character_api.test.ts` 中的 Private Zone 请求；
-3. `src/stores/private-zoom/__tests__`；
+3. `src/stores/private-zone/__tests__`；
-4. `src/app/private-zoom/__tests__` 与组件测试；
+4. `src/app/private-zone/__tests__` 与组件测试；
 5. Elio、Maya、Nayeli 列表互不串联；
 6. 登录身份变化会刷新当前角色列表；
 7. 成功、余额不足、价格变化、重复解锁、退款失败和 not found 分支；

docs/docker-image-ci.md

@@ -8,13 +8,13 @@
 
 | Workflow | 触发时机 | 职责 |
 | --- | --- | --- |
-| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
+| `.gitea/workflows/ci.yml` | `dev`、`main`、`pre` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
-| `.gitea/workflows/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
+| `.gitea/workflows/docker-image.yml` | `main`、`pre` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
 
 这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。
 
-`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`test`
+`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`pre`
-分支为快速部署测试环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
+分支用于快速部署预发环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
 `ci.yml` 会同时执行完整检查并提供测试结果。
 
 ## 必需 Secrets
@@ -39,7 +39,7 @@ Next.js 的 `NEXT_PUBLIC_*` 会在构建期固化到产物中，因此测试环
 
 ## 镜像 Tag 规则
 
-`test` 分支发布：
+`pre` 分支发布时继续使用现有 `test-*` 运行镜像标签：
 
 ```bash
 REGISTRY_IMAGE:test-<short_sha>
@@ -81,7 +81,7 @@ volumes:
 
 ## 验证方式
 
-推送到 `test` 分支后，检查 Actions 日志中是否出现：
+推送到 `pre` 分支后，检查 Actions 日志中是否出现：
 
 ```text
 Build Docker image
@@ -124,4 +124,4 @@ gitea.banlv-ai.com/admin/cozsweet-web:prod-<short_sha>
 - `prod-*` 精确 tag 只保留最近 3 个，`prod-latest` 不计入也不删除。
 - 当前刚推送的 `IMAGE_VERSION_TAG` 永远不会被删除。
 
-SSH 部署成功后，服务器本机只保留当前环境正在运行的一个精确版本镜像；测试环境清理旧 `test-*`，生产环境清理旧 `prod-*`。
+SSH 部署成功后，服务器本机只保留当前环境正在运行的一个精确版本镜像；预发环境清理旧 `test-*`，生产环境清理旧 `prod-*`。

docs/external-entry/README.md

@@ -19,7 +19,7 @@ https://<APP_HOST>/external-entry?<参数>
 
 | 参数 | 可选值或格式 | 用途 |
 | --- | --- | --- |
-| `target` | `chat`、`tip`、`private-zoom` | 指定进入的页面；不传或值无效时进入聊天页。 |
+| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。 |
 | `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
 | `psid` | string | 传入 Facebook Page-scoped User ID。 |
 | `mode` | `promotion` | 开启聊天促销模式。 |
@@ -78,13 +78,13 @@ https://<APP_HOST>/external-entry?target=tip
 私密空间：
 
 ```text
-https://<APP_HOST>/external-entry?target=private-zoom
+https://<APP_HOST>/external-entry?target=private-zone
 ```
 
 进入 Nayeli 私密空间：
 
 ```text
-https://<APP_HOST>/external-entry?target=private-zoom&character=nayeli
+https://<APP_HOST>/external-entry?target=private-zone&character=nayeli
 ```
 
 `psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。

docs/external-entry/debug-links.md

@@ -40,8 +40,8 @@
 
 | 角色 | 链接 |
 | --- | --- |
-| Elio | [打开 Elio 私密空间](http://localhost:3000/external-entry?target=private-zoom&character=elio) |
+| Elio | [打开 Elio 私密空间](http://localhost:3000/external-entry?target=private-zone&character=elio) |
-| Maya | [打开 Maya 私密空间](http://localhost:3000/external-entry?target=private-zoom&character=maya) |
+| Maya | [打开 Maya 私密空间](http://localhost:3000/external-entry?target=private-zone&character=maya) |
-| Nayeli | [打开 Nayeli 私密空间](http://localhost:3000/external-entry?target=private-zoom&character=nayeli) |
+| Nayeli | [打开 Nayeli 私密空间](http://localhost:3000/external-entry?target=private-zone&character=nayeli) |
 
 如需为其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。对于不带查询参数的默认入口，请改为追加 `?psid=27511427698460020`。

docs/external-entry/links.md

@@ -18,9 +18,9 @@
 | 咖啡打赏 | [打开咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip) |
 | Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=maya) |
 | Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=nayeli) |
-| 私密空间 | [打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zoom) |
+| 私密空间 | [打开私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zoom&character=maya) |
+| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zoom&character=nayeli) |
+| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=nayeli) |
 
 ## 正式环境
 
@@ -36,8 +36,8 @@
 | 咖啡打赏 | [打开咖啡打赏](https://cozsweet.com/external-entry?target=tip) |
 | Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=maya) |
 | Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=nayeli) |
-| 私密空间 | [打开私密空间](https://cozsweet.com/external-entry?target=private-zoom) |
+| 私密空间 | [打开私密空间](https://cozsweet.com/external-entry?target=private-zone) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://cozsweet.com/external-entry?target=private-zoom&character=maya) |
+| Maya 私密空间 | [打开 Maya 私密空间](https://cozsweet.com/external-entry?target=private-zone&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://cozsweet.com/external-entry?target=private-zoom&character=nayeli) |
+| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://cozsweet.com/external-entry?target=private-zone&character=nayeli) |
 
 如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。

docs/frontend-integration/2026-07-22-private-zone-rename.md

@@ -1,12 +1,12 @@
-# Private Zoom 全链路改名联调说明
+# Private Zone 全链路改名联调说明
 
 - 日期：2026-07-22
 - 目标环境：本地、`pre`、生产
-- 当前状态：已实现待联调
+- 当前状态：已验证
 
 ## 1. 目标
 
-原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zoom`，并同步切换页面路由、API 路径和公开枚举值。
+原功能名称存在拼写错误。本次将前端、unified 后端、Manager、数据库、埋点和文档中的正式命名统一为 `Private Zone`，并同步切换页面路由、API 路径和公开枚举值。
 
 ## 2. 环境地址
 
@@ -19,12 +19,12 @@
 
 前端已完成以下修改：
 
-- 页面路由统一为 `/private-zoom` 和 `/characters/{characterSlug}/private-zoom`。
+- 页面路由统一为 `/private-zone` 和 `/characters/{characterSlug}/private-zone`。
-- 外部入口参数统一为 `target=private-zoom`。
+- 外部入口参数统一为 `target=private-zone`。
-- 支付回跳参数统一为 `returnTo=private-zoom`。
+- 支付回跳参数统一为 `returnTo=private-zone`。
-- 类型、Repository、API client、XState actor、Provider 和资源目录统一使用 `privateZoom`、`PrivateZoom`、`private-zoom` 或 `private_zoom`。
+- 类型、Repository、API client、XState actor、Provider 和资源目录统一使用 `privateZone`、`PrivateZone`、`private-zone` 或 `private_zone`。
-- 埋点键统一为 `navigation.private_zoom`、`chat.open_private_zoom_from_avatar` 等新名称。
+- 埋点键统一为 `navigation.private_zone`、`chat.open_private_zone_from_avatar` 等新名称。
-- 角色能力字段统一为 `capabilities.privateZoom`。
+- 角色能力字段统一为 `capabilities.privateZone`。
 
 旧页面和旧查询参数不再作为正式入口保留。发布时必须让前后端属于同一个发布批次。
 
@@ -34,19 +34,19 @@
 
 | 方法 | 新路径 | 用途 |
 | --- | --- | --- |
-| `GET` | `/api/private-zoom/albums` | 查询付费图片包 |
+| `GET` | `/api/private-zone/albums` | 查询付费图片包 |
-| `POST` | `/api/private-zoom/albums/{albumId}/unlock` | 解锁图片包 |
+| `POST` | `/api/private-zone/albums/{albumId}/unlock` | 解锁图片包 |
-| `GET` | `/api/private-zoom/moments` | 查询朋友圈式内容 |
+| `GET` | `/api/private-zone/moments` | 查询朋友圈式内容 |
-| `POST` | `/api/private-zoom/moments/{momentId}/unlock` | 解锁单条内容 |
+| `POST` | `/api/private-zone/moments/{momentId}/unlock` | 解锁单条内容 |
-| `GET` | `/api/private-zoom/config` | 查询当前角色和用户解锁配置 |
+| `GET` | `/api/private-zone/config` | 查询当前角色和用户解锁配置 |
-| `GET` | `/api/private-zoom/diaries` | 查询关系日记 |
+| `GET` | `/api/private-zone/diaries` | 查询关系日记 |
-| `POST` | `/api/private-zoom/diaries/{diaryId}/seen` | 标记关系日记已读 |
+| `POST` | `/api/private-zone/diaries/{diaryId}/seen` | 标记关系日记已读 |
-| `POST` | `/api/private-zoom/diaries/{diaryId}/unlock` | 解锁关系日记 |
+| `POST` | `/api/private-zone/diaries/{diaryId}/unlock` | 解锁关系日记 |
 
 ### 4.1 图片包列表
 
 ```http
-GET /api/private-zoom/albums?characterId=elio&limit=20
+GET /api/private-zone/albums?characterId=elio&limit=20
 Authorization: Bearer <TOKEN>
 ```
 
@@ -59,14 +59,14 @@ Authorization: Bearer <TOKEN>
 调用示例：
 
 ```bash
-curl 'https://proapi.banlv-ai.com/api/private-zoom/albums?characterId=elio&limit=20' \
+curl 'https://proapi.banlv-ai.com/api/private-zone/albums?characterId=elio&limit=20' \
   -H 'Authorization: Bearer <TOKEN>'
 ```
 
 ### 4.2 解锁图片包
 
 ```http
-POST /api/private-zoom/albums/{albumId}/unlock
+POST /api/private-zone/albums/{albumId}/unlock
 Authorization: Bearer <TOKEN>
 Content-Type: application/json
 ```
@@ -77,7 +77,7 @@ Content-Type: application/json
 | `expectedCost` | body | integer | 否 | 是 | 前端确认价格；与后端价格不一致时拒绝解锁 |
 
 ```bash
-curl -X POST 'https://proapi.banlv-ai.com/api/private-zoom/albums/<ALBUM_ID>/unlock' \
+curl -X POST 'https://proapi.banlv-ai.com/api/private-zone/albums/<ALBUM_ID>/unlock' \
   -H 'Authorization: Bearer <TOKEN>' \
   -H 'Content-Type: application/json' \
   -d '{"expectedCost":320}'
@@ -86,8 +86,8 @@ curl -X POST 'https://proapi.banlv-ai.com/api/private-zoom/albums/<ALBUM_ID>/unl
 ### 4.3 Moments 内容与解锁
 
 ```http
-GET /api/private-zoom/moments?characterId=elio&limit=20
+GET /api/private-zone/moments?characterId=elio&limit=20
-POST /api/private-zoom/moments/{momentId}/unlock
+POST /api/private-zone/moments/{momentId}/unlock
 ```
 
 解锁请求体与图片包一致，`expectedCost` 为可选整数。响应中的正式分类值同步改为：
@@ -95,8 +95,8 @@ POST /api/private-zoom/moments/{momentId}/unlock
 ```json
 {
   "lockDetail": {
-    "type": "private_zoom_moment",
+    "type": "private_zone_moment",
-    "reason": "private_zoom_moment"
+    "reason": "private_zone_moment"
   }
 }
 ```
@@ -105,24 +105,24 @@ POST /api/private-zoom/moments/{momentId}/unlock
 
 | 使用位置 | 新值 | 类型 |
 | --- | --- | --- |
-| `/api/chat/unlock-private` 的 `lockType` 别名 | `private_zoom` | string enum |
+| `/api/chat/unlock-private` 的 `lockType` 别名 | `private_zone` | string enum |
-| 日程导入 `contentType` 别名 | `private_zoom` | string enum，归一化为 `paid_content` |
+| 日程导入 `contentType` 别名 | `private_zone` | string enum，归一化为 `paid_content` |
-| 外部入口 `target` | `private-zoom` | string enum |
+| 外部入口 `target` | `private-zone` | string enum |
-| 支付回跳 `returnTo` | `private-zoom` | string enum |
+| 支付回跳 `returnTo` | `private-zone` | string enum |
-| 锁定详情分类 | `private_zoom_moment` | string enum |
+| 锁定详情分类 | `private_zone_moment` | string enum |
 
 ## 6. 数据库迁移
 
 因为 `pre` 与生产当前共用 `https://dbapi.banlv-ai.com`，预发部署前先执行 unified 仓库中的临时桥接脚本：
 
 ```text
-database/private-zoom-bridge.sql
+database/private-zone-bridge.sql
 ```
 
 桥接脚本会创建新表并在切换窗口内保持新旧解锁写入双向同步。生产前后端全部切换完成后，再执行最终迁移：
 
 ```text
-database/private-zoom-migration.sql
+database/private-zone-migration.sql
 ```
 
 迁移会在同一事务中完成：
@@ -130,7 +130,7 @@ database/private-zoom-migration.sql
 - 将历史解锁表无损重命名；新旧表同时存在时先合并再删除旧表。
 - 重命名关联约束、索引、策略和触发器。
 - 合并 `users.preferences` 中历史解锁键，防止已解锁内容重新锁定。
-- 把 `credit_ledger` 历史分类迁移到 `private_zoom` 和 `private_zoom_moment`。
+- 把 `credit_ledger` 历史分类迁移到 `private_zone` 和 `private_zone_moment`。
 - 定向迁移历史埋点键、页面 URL 和系统媒体路径，不改写用户聊天正文。
 - 删除切换窗口使用的双写触发器和函数。
 - 支持重复执行。
@@ -140,13 +140,13 @@ database/private-zoom-migration.sql
 这是破坏性命名修正，不保留旧 API、旧页面路由或旧公开枚举作为正式兼容层。必须按以下顺序发布：
 
 1. 备份数据库并记录当前 unified、前端和 Manager 版本。
-2. 执行 `database/private-zoom-bridge.sql`，确认新旧表双向写入一致。
+2. 执行 `database/private-zone-bridge.sql`，确认新旧表双向写入一致。
-3. 部署 unified `pre`，验证所有 `/api/private-zoom/*` 接口。
+3. 部署 unified `pre`，验证所有 `/api/private-zone/*` 接口。
 4. 部署前端 `pre`，验证页面、外部入口、解锁和支付回跳。
 5. Manager 更新后验证积分用途显示为新分类。
 6. `pre` 验证通过后，先启动新生产后端并临时配置旧 API 到新 API 的 Nginx 转发。
-7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zoom/*`。
+7. 切换生产后端，再部署同批次生产前端；确认新前端只调用 `/api/private-zone/*`。
-8. 删除临时 Nginx 转发，执行 `database/private-zoom-migration.sql` 清理旧数据库对象。
+8. 删除临时 Nginx 转发，执行 `database/private-zone-migration.sql` 清理旧数据库对象。
 
 ## 8. 错误与界面状态
 
@@ -154,32 +154,35 @@ database/private-zoom-migration.sql
 - `403`：游客访问仅注册用户可用的关系日记操作，展示现有注册引导。
 - `404`：角色、图片包、内容或日记不存在，展示现有空状态或失效提示。
 - `409`：`expectedCost` 与后端价格不同，刷新列表后重新确认。
-- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zoom` 返回原角色页面。
+- `402` 或业务余额不足错误：进入现有充值流程，并使用 `returnTo=private-zone` 返回原角色页面。
 - 网络失败：不修改本地解锁状态，保留重试入口。
 
 ## 9. 验收用例
 
-1. `/characters/elio/private-zoom`、Maya 和 Nayeli 对应页面均可打开。
+1. `/characters/elio/private-zone`、Maya 和 Nayeli 对应页面均可打开。
-2. `GET /api/private-zoom/albums` 返回当前角色内容，角色之间不混用。
+2. `GET /api/private-zone/albums` 返回当前角色内容，角色之间不混用。
 3. 已解锁历史记录在迁移后保持解锁状态，不重复扣积分。
 4. 新解锁成功后刷新页面仍为已解锁状态。
-5. 积分不足进入充值页后，回跳到原角色 `/private-zoom` 页面。
+5. 积分不足进入充值页后，回跳到原角色 `/private-zone` 页面。
-6. `target=private-zoom&character=nayeli` 进入 Nayeli 对应页面。
+6. `target=private-zone&character=nayeli` 进入 Nayeli 对应页面。
 7. Manager 的积分用途不再出现旧分类。
 8. 三个仓库执行旧命名残留扫描，结果为 `0`。
 
 ## 10. 当前测试证据
 
 - unified：`316 passed`。
-- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zoom` 页面。
+- 前端：TypeScript 类型检查通过；Vitest `639 passed`；ESLint 通过；契约测试 `4 passed`；生产构建通过并生成三个角色的 `/private-zone` 页面。
 - Manager：`75 passed`。
 - PostgreSQL 16 临时库：升级、重复升级、回滚和再次升级全部通过；历史解锁、偏好键、积分账本、埋点、媒体路径和数据库对象名均通过断言，临时容器已删除。
+- `pre`：unified `71da49b` 和前端 `35939e7` 已验证；新 API 已注册 `8` 条 `/api/private-zone/*` 路径，旧 API 路径数量为 `0`；新页面返回 `200`，旧页面返回 `404`。
+- 生产：unified 镜像 `ai-boyfriend-unified:prod-20260722-71da49b`（镜像 ID `sha256:755ef5741856d83d7d808e7df8ee259b6fa5fb94fe333b523ee280ed1d5f674b`）和前端镜像 `prod-35939e7` 已健康运行；Manager 当前版本为 `6eea005`。
+- 生产接口：测试账号调用 `GET https://api.banlv-ai.com/api/private-zone/config?characterId=elio` 返回 `200`，`success=true`；旧版 API 路径在所有公开 API 入口均返回 `404`。
+- 生产数据库：最终迁移已执行，旧表、桥接函数、桥接触发器、旧偏好键、旧积分分类和旧埋点值的残留数量均为 `0`。
 
 ## 11. 回滚影响
 
-最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zoom-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。
+最终迁移执行前可直接恢复旧应用，桥接表会保留双向一致的数据。最终迁移执行后，回滚必须同时执行 unified 仓库中的 `database/private-zone-rollback.sql`。回滚前应停止写入，先保存切换后的新增解锁记录，再执行逆向迁移并恢复旧应用版本。不得只恢复前端或只恢复 unified。
 
 ## 12. 待确认事项
 
-- `pre` 浏览器真实联调和生产发布尚未执行。
+- 无。
-- 生产镜像 ID 将在发布前固化到发布记录。

docs/gitea-actions-ssh-deploy.md

@@ -3,7 +3,7 @@
 当前推荐部署链路：
 
 ```text
-push test/main
+push pre/main
 → Gitea Actions 构建并推送 Docker 镜像
 → Actions 通过 SSH 登录目标服务器
 → 目标服务器 docker pull 指定镜像 tag
@@ -16,7 +16,7 @@ push test/main
 
 | 分支 | 环境 | 镜像 tag | 宿主机端口 | 默认服务器目录 | 容器名 |
 | --- | --- | --- | --- | --- | --- |
-| `test` | 测试环境 | `test-<short_sha>` | `9135` | `/opt/cozsweet-web-test` | `cozsweet-web-test` |
+| `pre` | 预发环境 | `test-<short_sha>` | `9135` | `/opt/cozsweet-web-test` | `cozsweet-web-test` |
 | `main` | 生产环境 | `prod-<short_sha>` | `9185` | `/opt/cozsweet-web-prod` | `cozsweet-web-prod` |
 
 ## Gitea Secrets
@@ -75,14 +75,14 @@ prod-<short_sha> 最近 3 个
 
 `test-latest` / `prod-latest` 不计入保留数量，也不会主动删除。
 
-部署脚本会在 `docker compose up` 成功后清理服务器本机旧镜像，只保留当前环境正在运行的一个精确版本镜像：测试环境保留当前 `test-<short_sha>`，生产环境保留当前 `prod-<short_sha>`。
+部署脚本会在 `docker compose up` 成功后清理服务器本机旧镜像，只保留当前环境正在运行的一个精确版本镜像：预发环境保留当前 `test-<short_sha>`，生产环境保留当前 `prod-<short_sha>`。
 
 ## 本地发布入口
 
 本地发布脚本现在只负责推送 Gitea 分支，触发 Actions：
 
 ```bash
-# 测试环境
+# 预发环境
 ./scripts/release/pre_release_web.sh
 
 # 生产环境
@@ -92,16 +92,16 @@ prod-<short_sha> 最近 3 个
 也可以直接推送：
 
 ```bash
-git push gitea test
+git push gitea pre
 git push --force gitea main
 ```
 
 ## 验证
 
-测试环境：
+预发环境：
 
 ```bash
-ssh <user>@<test-host>
+ssh <user>@<pre-host>
 cd /opt/cozsweet-web-test
 docker compose ps
 curl -I http://127.0.0.1:9135/

e2e/README.md

@@ -27,8 +27,8 @@ pnpm exec playwright install chromium
 For local development on macOS, `pnpm test:e2e:chrome` can reuse the installed Google Chrome.
 
 `pnpm test:e2e:mobile-smoke` runs the critical authentication, logout, token
-refresh and paid-image unlock paths with the Pixel 7 profile. CI runs this tier
+refresh and paid-image unlock paths with the Pixel 7 profile. CI 在所有 pull
-on every pull request and `dev` / `test` / `main` push.
+request 以及 `dev` / `pre` / `main` push 时运行这一层测试。
 
 ## Environment overrides
 

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/auth/email-login-from-other-options.spec.ts

@@ -31,5 +31,5 @@ test("user can email login from other sign-in options and return to chat", async
   expect(["desktop", "android"]).toContain(loginRequest?.postDataJSON().platform);
 
   await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
-  await expect(page.getByRole("button", { name: "Profile" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
 });

e2e/specs/mock/auth/logout-from-profile.spec.ts

@@ -27,9 +27,12 @@ test("user can log out from the profile after email login", async ({
   await expect(page).toHaveURL(/\/auth(?:\?.*)?$/);
   await switchToEmailSignIn(page);
   await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
-  await expect(page.getByRole("button", { name: "Profile" })).toBeVisible();
+  await page.getByRole("link", { name: "Back to home" }).click();
+  await expect(page).toHaveURL(
+    new RegExp(defaultCharacterSplashPath.replace("?", "\\?") + "$"),
+  );
 
-  await page.getByRole("button", { name: "Profile" }).click();
+  await page.getByRole("button", { name: "Menu" }).click();
   await expect(page).toHaveURL(
     new RegExp(defaultCharacterProfilePath.replace("?", "\\?") + "$"),
   );

e2e/specs/mock/chat/chat-avatar-navigation.spec.ts

@@ -42,7 +42,7 @@ test("guest user avatar returns to Profile after sign-in", async ({
 });
 
 for (const character of characters) {
-  test(`${character.displayName} avatar opens the matching Private Zoom`, async ({
+  test(`${character.displayName} avatar opens the matching Private Zone`, async ({
     page,
   }) => {
     await enterCharacterChat(page, character.slug);
@@ -50,13 +50,13 @@ for (const character of characters) {
 
     await page
       .getByRole("button", {
-        name: `Open ${character.displayName}'s private zoom`,
+        name: `Open ${character.displayName}'s private zone`,
       })
       .last()
       .click();
 
     await expect(page).toHaveURL(
-      new RegExp(`/characters/${character.slug}/private-zoom(?:\\?.*)?$`),
+      new RegExp(`/characters/${character.slug}/private-zone(?:\\?.*)?$`),
     );
   });
 }

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,206 @@
+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);
+    const iosDownload = page.getByRole("button", { name: "Download" });
+    await expect(iosDownload).toBeVisible();
+    await iosDownload.click();
+    await expect(
+      page.getByRole("heading", { name: "Add CozSweet to Home Screen" }),
+    ).toBeVisible();
+    await expect(page.getByRole("dialog")).toContainText(
+      "In Safari, tap the Share button, then choose “Add to Home Screen”.",
+    );
+    await savePreview(page, "mobile-ios-external-chat-download.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

@@ -0,0 +1,237 @@
+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 { clearBrowserState } from "@e2e/fixtures/test-helpers";
+
+const characters = [
+  {
+    id: "elio",
+    slug: "elio",
+    displayName: "Elio Silvestri",
+    shortName: "Elio",
+    cover: "elio.png",
+    splashCover: "elio.png",
+  },
+  {
+    id: "maya-tan",
+    slug: "maya",
+    displayName: "Maya Tan",
+    shortName: "Maya",
+    cover: "maya.webp",
+    splashCover: "maya-home.webp",
+  },
+  {
+    id: "nayeli-cervantes",
+    slug: "nayeli",
+    displayName: "Nayeli Cervantes",
+    shortName: "Nayeli",
+    cover: "nayeli.webp",
+    splashCover: "nayeli.webp",
+  },
+] as const;
+
+const previewDirectory = path.join(
+  process.cwd(),
+  ".codex",
+  "artifacts",
+  "frontend-preview",
+  "2026-07-22",
+  "multi-role-commercial",
+);
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerMultiRoleCommercialMocks(page);
+});
+
+for (const character of characters) {
+  test(`${character.displayName} homepage renders its assigned cover`, async ({
+    page,
+  }, testInfo) => {
+    const mobile = testInfo.project.name.includes("mobile");
+    await page.setViewportSize(
+      mobile ? { width: 390, height: 844 } : { width: 1440, height: 900 },
+    );
+
+    await page.goto(`/characters/${character.slug}/splash`);
+
+    const cover = page.locator(`img[src*="${character.splashCover}"]`);
+    await expect(cover).toBeVisible();
+    await expect(
+      page.getByRole("navigation", { name: "Primary navigation" }),
+    ).toContainText("Private Zone");
+    await expect
+      .poll(() =>
+        cover.evaluate((image: HTMLImageElement) =>
+          image.complete ? image.naturalWidth : 0,
+        ),
+      )
+      .toBeGreaterThan(0);
+
+    if (
+      process.env.FRONTEND_PREVIEW_SCREENSHOTS === "1" &&
+      character.id !== "elio"
+    ) {
+      await page.screenshot({
+        path: path.join(
+          previewDirectory,
+          `${character.slug}-${mobile ? "mobile-390x844" : "desktop-1440x900"}.png`,
+        ),
+        animations: "disabled",
+      });
+    }
+  });
+
+  test(`${character.displayName} can open a character-scoped Private Zone`, async ({
+    page,
+  }) => {
+    const albumRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/private-zone/albums" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+
+    await page.goto(`/characters/${character.slug}/private-zone`);
+
+    await albumRequest;
+    await expect(
+      page.getByRole("heading", { name: "Private albums" }),
+    ).toBeVisible();
+    await expect(page.getByText(character.displayName).last()).toBeVisible();
+    const albumButton = page.getByRole("button", {
+      name: `View locked collection with 8 images from ${character.displayName}`,
+    });
+    if (character.id === "maya-tan") {
+      await expect(albumButton).toHaveCount(0);
+      await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+      await expect(page.getByText("No private albums yet.")).toHaveCount(0);
+    } else {
+      await expect(albumButton).toBeVisible();
+    }
+  });
+
+  test(`${character.displayName} receives a character-scoped Tip catalog`, async ({
+    page,
+  }) => {
+    const catalogRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/payment/gift-products" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+
+    await page.goto(`/characters/${character.slug}/tip`);
+
+    await catalogRequest;
+    await expect(
+      page.getByRole("heading", { name: `Buy ${character.shortName} a coffee` }),
+    ).toBeVisible();
+    await expect(page.getByRole("radio", { name: /Small Coffee/ })).toBeChecked();
+    await expect(
+      page.getByRole("button", { name: "Order and Buy" }),
+    ).toBeEnabled();
+    await expect(
+      page.getByText("This character does not have any gifts available yet."),
+    ).toHaveCount(0);
+  });
+}
+
+test("a real Private Zone request failure still offers Retry", async ({
+  page,
+}) => {
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({ status: 503, json: { message: "Albums unavailable" } });
+  });
+
+  await page.goto("/characters/maya/private-zone");
+
+  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
+});
+
+async function registerMultiRoleCommercialMocks(page: Page): Promise<void> {
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    const character =
+      characters.find((candidate) => candidate.id === characterId) ?? characters[0];
+
+    const hasCompleteAlbum = character.id !== "maya-tan";
+    await route.fulfill({
+      json: apiEnvelope({
+        creditBalance: 1000,
+        pendingImageCount: hasCompleteAlbum ? 0 : 7,
+        hasIncompleteContent: !hasCompleteAlbum,
+        items: hasCompleteAlbum ? [
+          {
+            albumId: `album-${character.id}`,
+            title: `${character.shortName} private photos`,
+            content: null,
+            previewText: "Unlock this private album",
+            imageCount: 8,
+            images: [
+              {
+                url: `/images/private-zone/banner/${character.slug}.png`,
+                locked: true,
+                index: 0,
+              },
+            ],
+            locked: true,
+            unlocked: false,
+            unlockCost: 320,
+            publishedAt: "2026-07-22T10:00:00+08:00",
+            lockDetail: { locked: true },
+          },
+        ] : [],
+      }),
+    });
+  });
+
+  await page.route("**/api/payment/gift-products**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    const planPrefix =
+      characterId === "elio"
+        ? "tip"
+        : `tip_${characterId.replaceAll("-", "_")}`;
+
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        categories: [
+          {
+            category: "coffee",
+            name: "Coffee",
+            productCount: 1,
+            imageUrl: null,
+          },
+        ],
+        plans: [
+          {
+            planId: `${planPrefix}_coffee_usd_4_99`,
+            planName: "Small Coffee",
+            orderType: "tip",
+            tipType: "coffee_small",
+            category: "coffee",
+            characterId,
+            description: "A character-scoped coffee gift",
+            imageUrl: null,
+            amountCents: 499,
+            currency: "USD",
+            autoRenew: false,
+            isFirstRechargeOffer: false,
+            firstRechargeDiscountPercent: 0,
+            promotionType: null,
+          },
+        ],
+      }),
+    });
+  });
+}

e2e/specs/mock/paid-image.spec.ts

@@ -1,6 +1,8 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { createPaidImageHistoryResponse } from "@e2e/fixtures/data/chat";
 import {
   paidImageDisplayMessageId,
   paidImageMessageId,
@@ -97,3 +99,38 @@ test("guest can unlock a paid image after email login and subscription payment",
   expect(new URL(page.url()).pathname).toBe(defaultCharacterChatPath);
   await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
 });
+
+test("fullscreen image closes from its back button, the image, and browser history Back", async ({
+  page,
+}) => {
+  await page.route("**/api/chat/history**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope(createPaidImageHistoryResponse(true)),
+    });
+  });
+  await enterChatFromSplash(page);
+  await dismissChatInterruptions(page);
+
+  const imageButton = page.getByRole("button", {
+    name: "Open image in fullscreen",
+  });
+  const imageDialog = page.getByRole("dialog", { name: "Fullscreen image" });
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await imageDialog.getByRole("button", { name: "Back" }).click();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await imageDialog.locator("img").click();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+
+  await imageButton.click();
+  await expect(imageDialog).toBeVisible();
+  await page.goBack();
+  await expect(imageDialog).toHaveCount(0);
+  await expect(page).toHaveURL(defaultCharacterChatPath);
+});

public/manifest.json

@@ -11,13 +11,13 @@
   "lang": "en",
   "icons": [
     {
-      "src": "/images/icons/Icon-192.png",
+      "src": "/images/icons/Icon-192.png?v=20260724",
       "sizes": "192x192",
       "type": "image/png",
       "purpose": "any"
     },
     {
-      "src": "/images/icons/Icon-512.png",
+      "src": "/images/icons/Icon-512.png?v=20260724",
       "sizes": "512x512",
       "type": "image/png",
       "purpose": "any"

scripts/contracts/__tests__/openapi-contract.test.mjs

@@ -13,13 +13,13 @@ describe("OpenAPI contract comparison", () => {
         chatHistory: { method: "get", path: "/api/chat/history" },
         unlockAlbum: {
           method: "post",
-          path: "/api/private-zoom/albums/{albumId}/unlock",
+          path: "/api/private-zone/albums/{albumId}/unlock",
         },
       },
       {
         paths: {
           "/api/chat/history": { get: {} },
-          "/api/private-zoom/albums/{album_id}/unlock/": { post: {} },
+          "/api/private-zone/albums/{album_id}/unlock/": { post: {} },
         },
       },
     );

scripts/deploy/_deploy_lib.sh

@@ -3,7 +3,7 @@
 # 推送指定分支到指定远端。
 # 当前发布由 Gitea Actions 构建镜像并通过 SSH 部署；本脚本只负责触发分支 push。
 # 调用方：deploy_web.sh（production）→ push_to_remote "gitea" "main"
-#        deploy_web_test.sh（test）→ push_to_remote "gitea" "test"
+#        deploy_web_test.sh（pre）→ push_to_remote "gitea" "pre"
 push_to_remote() {
     local remote="$1"
     local branch="$2"

scripts/deploy/deploy_web_test.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # ==========================================
-# 测试环境 Web 部署脚本（Next.js + Gitea Actions SSH 部署模型）
+# 预发环境 Web 部署脚本（Next.js + Gitea Actions SSH 部署模型）
 # 原始 Dart: scripts/deploy/deploy_web_test.sh
 # ==========================================
 
@@ -11,7 +11,7 @@ source "$SCRIPT_DIR/_deploy_lib.sh"
 
 # 主函数
 main() {
-    push_to_remote "gitea" "test"
+    push_to_remote "gitea" "pre"
 }
 
 main

scripts/release/pre_release_web.sh

@@ -11,9 +11,9 @@ unset_git_hook_env() {
 
 unset_git_hook_env
 
-# Test 分支 worktree 路径
+# pre 分支 worktree 路径
-WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test"
+WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre"
-echo "=== 进入 test 分支 worktree ==="
+echo "=== 进入 pre 分支 worktree ==="
 cd "$WORKTREE_PATH" || { echo "错误: 无法进入 $WORKTREE_PATH"; exit 1; }
 
 echo "=== 检查当前分支 ==="
@@ -22,17 +22,17 @@ git branch --show-current
 echo "=== 变基到 dev 分支 ==="
 git rebase dev
 
-# 复制测试环境图标（source: $WORKTREE_PATH/icons/test → dest: $WORKTREE_PATH/public/）
+# 复制预发环境图标（运行资源目录仍为 icons/test）
-echo "=== 复制测试环境图标（icons/test → public/） ==="
+echo "=== 复制预发环境图标（icons/test → public/） ==="
 cp -f "$WORKTREE_PATH/icons/test/favicon.ico" "$WORKTREE_PATH/public/favicon.ico"
 cp -f "$WORKTREE_PATH/icons/test/icons/Icon-192.png" "$WORKTREE_PATH/public/images/icons/Icon-192.png"
 cp -f "$WORKTREE_PATH/icons/test/icons/Icon-512.png" "$WORKTREE_PATH/public/images/icons/Icon-512.png"
 
-# 准备测试环境变量（$WORKTREE_PATH/env-example/.env.local.example → $WORKTREE_PATH/.env.local）
+# 准备预发环境变量（运行配置仍使用 .env.local）
-echo "=== 准备测试环境变量（env-example/.env.local.example → .env.local） ==="
+echo "=== 准备预发环境变量（env-example/.env.local.example → .env.local） ==="
 cp -f "$WORKTREE_PATH/env-example/.env.local.example" "$WORKTREE_PATH/.env.local"
 
-echo "=== 执行构建部署脚本（测试环境）==="
+echo "=== 执行构建部署脚本（预发环境）==="
 ./scripts/deploy/deploy_web_test.sh
 
 echo "=== 预发布完成 ==="

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

@@ -85,8 +85,8 @@ describe("shared Tailwind components", () => {
       <CharacterAvatar
         src="/images/avatar/elio.png"
         alt="Elio Silvestri"
-        actionLabel="Open Elio's private zoom"
+        actionLabel="Open Elio's private zone"
-        analyticsKey="chat.open_private_zoom_from_avatar"
+        analyticsKey="chat.open_private_zone_from_avatar"
         onClick={() => undefined}
       />,
     );
@@ -100,10 +100,10 @@ describe("shared Tailwind components", () => {
 
     expect(characterHtml).toContain('<button type="button"');
     expect(characterHtml).toContain(
-      'aria-label="Open Elio&#x27;s private zoom"',
+      'aria-label="Open Elio&#x27;s private zone"',
     );
     expect(characterHtml).toContain(
-      'data-analytics-key="chat.open_private_zoom_from_avatar"',
+      'data-analytics-key="chat.open_private_zone_from_avatar"',
     );
     expect(userHtml).toContain('<button type="button"');
     expect(userHtml).toContain('aria-label="Open profile"');

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

@@ -0,0 +1,80 @@
+/* @vitest-environment jsdom */
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { pwaUtil } from "@/utils/pwa";
+
+import { FavoriteEntryButton } from "../favorite-entry-button";
+
+describe("FavoriteEntryButton install flow", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    window.localStorage.setItem("cozsweet:favorite_entry", "1");
+    vi.spyOn(BrowserDetector, "isInAppBrowser").mockReturnValue(false);
+    vi.spyOn(pwaUtil, "isInstalled").mockReturnValue(false);
+    vi.spyOn(pwaUtil, "prepareInstallPrompt").mockImplementation(() => undefined);
+    vi.spyOn(pwaUtil, "subscribe").mockReturnValue(() => undefined);
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    window.localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("shows Download on iOS and opens Safari add-to-home instructions", () => {
+    vi.spyOn(PlatformDetector, "isIOS").mockReturnValue(true);
+    vi.spyOn(PlatformDetector, "isAndroid").mockReturnValue(false);
+
+    renderButton();
+    const downloadButton = getButton("Download");
+    act(() => downloadButton.click());
+
+    expect(container.querySelector('[role="dialog"]')).not.toBeNull();
+    expect(container.textContent).toContain("Add CozSweet to Home Screen");
+    expect(container.textContent).toContain(
+      "In Safari, tap the Share button, then choose “Add to Home Screen”.",
+    );
+  });
+
+  it("opens the native Android install prompt and marks an accepted install as Saved", async () => {
+    vi.spyOn(PlatformDetector, "isIOS").mockReturnValue(false);
+    vi.spyOn(PlatformDetector, "isAndroid").mockReturnValue(true);
+    const install = vi.spyOn(pwaUtil, "install").mockResolvedValue("accepted");
+
+    renderButton();
+    await act(async () => {
+      getButton("Download").click();
+      await Promise.resolve();
+    });
+
+    expect(install).toHaveBeenCalledTimes(1);
+    expect(getButton("Saved")).not.toBeNull();
+  });
+
+  function renderButton(): void {
+    act(() => {
+      root.render(<FavoriteEntryButton characterSlug="elio" />);
+    });
+  }
+
+  function getButton(label: string): HTMLButtonElement {
+    const button = container.querySelector<HTMLButtonElement>(
+      `button[aria-label="${label}"]`,
+    );
+    if (!button) throw new Error(`Missing button: ${label}`);
+    return button;
+  }
+});

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

@@ -79,18 +79,20 @@ describe("core Tailwind components", () => {
       <AppBottomNav
         activeItem="chat"
         variant="dark"
-        privateZoomLabel="Maya Private Zoom"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateZoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
-    const privateZoomHtml = renderToStaticMarkup(
+    const privateZoneHtml = renderToStaticMarkup(
       <AppBottomNav
-        activeItem="privateZoom"
+        activeItem="privateZone"
         variant="warm"
-        privateZoomLabel="Maya Private Zoom"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateZoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
 
@@ -99,13 +101,15 @@ describe("core Tailwind components", () => {
     expect(chatHtml).toMatch(
       /<button[^>]*aria-current="page"[^>]*>.*?<span>Chat<\/span>/,
     );
-    expect(privateZoomHtml).toMatch(/class="[^"]*warm[^"]*"/);
+    expect(privateZoneHtml).toMatch(/class="[^"]*warm[^"]*"/);
-    expect(privateZoomHtml).toMatch(
+    expect(privateZoneHtml).toMatch(
-      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private Zoom<\/span>/,
+      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private Zone<\/span>/,
     );
     expect(chatHtml).toContain('data-analytics-key="navigation.chat"');
-    expect(privateZoomHtml).toContain(
+    expect(privateZoneHtml).toContain(
-      'data-analytics-key="navigation.private_zoom"',
+      '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,26 +1,28 @@
 "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" | "privateZoom";
+export type AppBottomNavItem = "chat" | "privateZone" | "menu";
 export type AppBottomNavVariant = "warm" | "dark";
 
 export interface AppBottomNavProps {
   activeItem?: AppBottomNavItem | null;
   variant?: AppBottomNavVariant;
-  privateZoomLabel: string;
+  privateZoneLabel: string;
   onChatClick: () => void;
-  onPrivateZoomClick: () => void;
+  onPrivateZoneClick: () => void;
+  onMenuClick: () => void;
 }
 
 export function AppBottomNav({
   activeItem = null,
   variant = "warm",
-  privateZoomLabel,
+  privateZoneLabel,
   onChatClick,
-  onPrivateZoomClick,
+  onPrivateZoneClick,
+  onMenuClick,
 }: AppBottomNavProps) {
   return (
     <nav className={getRootClass(variant)} aria-label="Primary navigation">
@@ -37,14 +39,25 @@ export function AppBottomNav({
       </button>
       <button
         type="button"
-        data-analytics-key="navigation.private_zoom"
+        data-analytics-key="navigation.private_zone"
-        data-analytics-label="Private Zoom navigation"
+        data-analytics-label="Private Zone navigation"
-        className={getButtonClass(activeItem === "privateZoom")}
+        className={getButtonClass(activeItem === "privateZone")}
-        aria-current={activeItem === "privateZoom" ? "page" : undefined}
+        aria-current={activeItem === "privateZone" ? "page" : undefined}
-        onClick={onPrivateZoomClick}
+        onClick={onPrivateZoneClick}
       >
         <Camera size={20} aria-hidden="true" />
-        <span>{privateZoomLabel}</span>
+        <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,175 @@
+.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;
+}
+
+.guideBackdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 240;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding:
+    calc(18px + var(--app-safe-top, 0px))
+    calc(18px + var(--app-safe-right, 0px))
+    calc(18px + var(--app-safe-bottom, 0px))
+    calc(18px + var(--app-safe-left, 0px));
+  background: rgba(15, 11, 18, 0.58);
+  backdrop-filter: blur(4px);
+}
+
+.guideDialog {
+  position: relative;
+  display: flex;
+  width: min(100%, 340px);
+  flex-direction: column;
+  align-items: center;
+  padding: 28px 22px 20px;
+  border: 1px solid rgba(255, 255, 255, 0.72);
+  border-radius: 28px;
+  background: rgba(255, 250, 252, 0.98);
+  box-shadow: 0 24px 70px rgba(33, 17, 26, 0.3);
+  color: #2d2026;
+  text-align: center;
+}
+
+.guideClose {
+  position: absolute;
+  top: 12px;
+  right: 12px;
+  display: inline-flex;
+  width: 36px;
+  height: 36px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: 999px;
+  background: rgba(45, 32, 38, 0.07);
+  color: #5b4a52;
+  cursor: pointer;
+}
+
+.guideIcon {
+  display: inline-flex;
+  width: 58px;
+  height: 58px;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 14px;
+  border-radius: 19px;
+  background: linear-gradient(135deg, #ff82b2, #f84d96);
+  box-shadow: 0 12px 26px rgba(248, 77, 150, 0.26);
+  color: #ffffff;
+}
+
+.guideDialog h2 {
+  margin: 0;
+  color: #281a21;
+  font-size: 21px;
+  font-weight: 850;
+  line-height: 1.2;
+}
+
+.guideDialog p {
+  margin: 12px 0 20px;
+  color: #685761;
+  font-size: 15px;
+  font-weight: 650;
+  line-height: 1.5;
+}
+
+.guideConfirm {
+  width: 100%;
+  min-height: 46px;
+  border: 0;
+  border-radius: 999px;
+  background: linear-gradient(135deg, #ff76ab, #f84d96);
+  box-shadow: 0 10px 24px rgba(248, 77, 150, 0.24);
+  color: #ffffff;
+  cursor: pointer;
+  font: inherit;
+  font-size: 16px;
+  font-weight: 850;
+}
+
+.guideClose:focus-visible,
+.guideConfirm:focus-visible {
+  outline: 2px solid #f84d96;
+  outline-offset: 3px;
+}

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

@@ -0,0 +1,162 @@
+"use client";
+
+import { useEffect, useId, useState } from "react";
+import { Download, Share2, Star, X } 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 [installGuide, setInstallGuide] = useState<
+    "ios" | "browser" | null
+  >(null);
+  const installGuideTitleId = useId();
+
+  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;
+  }, []);
+
+  useEffect(() => {
+    if (!installGuide) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setInstallGuide(null);
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [installGuide]);
+
+  const handleClick = async (): Promise<void> => {
+    if (mode === "favorite") {
+      await openChatInExternalBrowser({ characterSlug });
+      return;
+    }
+
+    if (mode === "download") {
+      if (PlatformDetector.isIOS()) {
+        setInstallGuide("ios");
+        return;
+      }
+      pwaUtil.prepareInstallPrompt();
+      const result = await pwaUtil.install();
+      if (result === "accepted" || pwaUtil.isInstalled()) {
+        setMode("saved");
+        setInstallGuide(null);
+        return;
+      }
+      if (result === "unavailable") setInstallGuide("browser");
+    }
+  };
+
+  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>
+      {installGuide ? (
+        <div
+          className={styles.guideBackdrop}
+          onClick={() => setInstallGuide(null)}
+          role="presentation"
+        >
+          <section
+            className={styles.guideDialog}
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby={installGuideTitleId}
+            onClick={(event) => event.stopPropagation()}
+          >
+            <button
+              type="button"
+              className={styles.guideClose}
+              onClick={() => setInstallGuide(null)}
+              aria-label="Close install instructions"
+            >
+              <X size={18} aria-hidden="true" />
+            </button>
+            <span className={styles.guideIcon} aria-hidden="true">
+              {installGuide === "ios" ? (
+                <Share2 size={28} strokeWidth={2.2} />
+              ) : (
+                <Download size={28} strokeWidth={2.2} />
+              )}
+            </span>
+            <h2 id={installGuideTitleId}>Add CozSweet to Home Screen</h2>
+            <p>
+              {installGuide === "ios"
+                ? "In Safari, tap the Share button, then choose “Add to Home Screen”."
+                : "Open your browser menu, then choose “Add to Home screen”."}
+            </p>
+            <button
+              type="button"
+              className={styles.guideConfirm}
+              onClick={() => setInstallGuide(null)}
+            >
+              Got it
+            </button>
+          </section>
+        </div>
+      ) : 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/characters/[characterSlug]/private-zone/layout.tsx

@@ -2,9 +2,9 @@ import type { ReactNode } from "react";
 import { notFound } from "next/navigation";
 
 import { getCharacterBySlug } from "@/data/constants/character";
-import { PrivateZoomRouteProvider } from "@/providers/private-zoom-route-provider";
+import { PrivateZoneRouteProvider } from "@/providers/private-zone-route-provider";
 
-export default async function CharacterPrivateZoomLayout({
+export default async function CharacterPrivateZoneLayout({
   children,
   params,
 }: {
@@ -13,11 +13,11 @@ export default async function CharacterPrivateZoomLayout({
 }) {
   const { characterSlug } = await params;
   const character = getCharacterBySlug(characterSlug);
-  if (!character?.capabilities.privateZoom) notFound();
+  if (!character?.capabilities.privateZone) notFound();
 
   return (
-    <PrivateZoomRouteProvider characterId={character.id}>
+    <PrivateZoneRouteProvider characterId={character.id}>
       {children}
-    </PrivateZoomRouteProvider>
+    </PrivateZoneRouteProvider>
   );
 }

src/app/characters/[characterSlug]/private-zone/page.tsx

@@ -0,0 +1,5 @@
+import { PrivateZoneScreen } from "@/app/private-zone/private-zone-screen";
+
+export default function CharacterPrivateZonePage() {
+  return <PrivateZoneScreen />;
+}

src/app/characters/[characterSlug]/private-zoom/page.tsx

@@ -1,5 +0,0 @@
-import { PrivateZoomScreen } from "@/app/private-zoom/private-zoom-screen";
-
-export default function CharacterPrivateZoomPage() {
-  return <PrivateZoomScreen />;
-}

src/app/chat/chat-screen.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, type CSSProperties } from "react";
+import { useEffect, useMemo, useRef, type CSSProperties } from "react";
 import Image from "next/image";
 import { useRouter, useSearchParams } from "next/navigation";
 
@@ -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";
@@ -68,6 +69,8 @@ export function ChatScreen() {
   const chatDispatch = useChatDispatch();
   const authState = useAuthState();
   const authDispatch = useAuthDispatch();
+  const imageOpenedFromChatRef = useRef(false);
+  const imageViewerClosingRef = useRef(false);
   useSplashLatestMessageSync({
     characterId: state.characterId,
     historyLoaded: state.historyLoaded,
@@ -118,12 +121,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,
@@ -131,6 +128,13 @@ export function ChatScreen() {
     loginStatus: authState.loginStatus,
   });
 
+  useEffect(() => {
+    if (!imageMessageId) {
+      imageOpenedFromChatRef.current = false;
+      imageViewerClosingRef.current = false;
+    }
+  }, [imageMessageId]);
+
   useEffect(() => {
     if (
       !imageMessageId ||
@@ -222,6 +226,7 @@ export function ChatScreen() {
   }
 
   function handleOpenImage(displayMessageId: string): void {
+    imageOpenedFromChatRef.current = true;
     router.push(
       buildChatImageOverlayUrl(displayMessageId, characterRoutes.chat),
       { scroll: false },
@@ -229,6 +234,13 @@ export function ChatScreen() {
   }
 
   function handleCloseImageViewer(): void {
+    if (imageViewerClosingRef.current) return;
+    imageViewerClosingRef.current = true;
+    if (imageOpenedFromChatRef.current) {
+      imageOpenedFromChatRef.current = false;
+      router.back();
+      return;
+    }
     router.replace(
       buildChatWithoutImageOverlayUrl(searchParams, characterRoutes.chat),
       { scroll: false },
@@ -253,8 +265,40 @@ export function ChatScreen() {
     );
   }
 
-  function handleOpenCharacterPrivateZoom(): void {
+  function handleOpenCharacterPrivateZone(): void {
-    router.push(characterRoutes.privateZoom);
+    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 (
@@ -276,13 +320,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"
               />
             }
           />
@@ -304,7 +348,9 @@ export function ChatScreen() {
             onUnlockImageMessage={handleUnlockImageMessage}
             onOpenImage={handleOpenImage}
             onUserAvatarClick={handleOpenUserProfile}
-            onCharacterAvatarClick={handleOpenCharacterPrivateZoom}
+            onCharacterAvatarClick={handleOpenCharacterPrivateZone}
+            onCommercialAction={handleCommercialAction}
+            onCommercialActionDismiss={handleCommercialActionDismiss}
             onLoadMoreHistory={() => {
               chatDispatch({ type: "ChatLoadMoreHistoryRequested" });
             }}

src/app/chat/components/__tests__/chat-input-bar.test.tsx

@@ -124,6 +124,36 @@ describe("ChatInputBar", () => {
     expect(getButton("Open chat actions")).not.toBeNull();
   });
 
+  it("suppresses the Facebook WebView click that follows a pointer send for 300ms", () => {
+    const now = vi.spyOn(Date, "now").mockReturnValue(1_000);
+    renderBar();
+    setTextareaValue(getTextarea(), "Hello Maya");
+    const sendButton = getButton("Send message");
+    const pointerDown = new Event("pointerdown", {
+      bubbles: true,
+      cancelable: true,
+    });
+    Object.defineProperty(pointerDown, "pointerType", { value: "touch" });
+
+    act(() => sendButton.dispatchEvent(pointerDown));
+
+    expect(mocks.dispatch).toHaveBeenCalledTimes(1);
+    expect(mocks.dispatch).toHaveBeenCalledWith({
+      type: "ChatSendMessage",
+      content: "Hello Maya",
+    });
+    expect(getTextarea().value).toBe("");
+    expect(getButton("Open chat actions")).toBe(sendButton);
+
+    now.mockReturnValue(1_299);
+    act(() => sendButton.click());
+    expect(container.querySelector('[aria-label="Chat actions"]')).toBeNull();
+
+    now.mockReturnValue(1_300);
+    act(() => sendButton.click());
+    expect(container.querySelector('[aria-label="Chat actions"]')).not.toBeNull();
+  });
+
   it("closes the menu on outside interaction and when disabled", () => {
     renderBar();
     act(() => getButton("Open chat actions").click());

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__/fullscreen-image-viewer.test.tsx

@@ -0,0 +1,80 @@
+/* @vitest-environment jsdom */
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from "vitest";
+
+import { FullscreenImageViewer } from "../fullscreen-image-viewer";
+
+describe("FullscreenImageViewer", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let onClose: Mock<() => void>;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    document.body.append(container);
+    root = createRoot(container);
+    onClose = vi.fn<() => void>();
+
+    act(() => {
+      root.render(
+        <FullscreenImageViewer
+          characterId="elio-silvestri"
+          remoteMessageId="message-1"
+          imageUrl="/chat-image.png"
+          onClose={onClose}
+        />,
+      );
+    });
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it("closes exactly once when the fullscreen image is tapped", () => {
+    const image = container.querySelector("img");
+    expect(image).not.toBeNull();
+
+    act(() => image?.click());
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes exactly once from the visible back button", () => {
+    const backButton = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Back"]',
+    );
+    expect(backButton).not.toBeNull();
+
+    act(() => backButton?.click());
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes from the backdrop and Escape key", () => {
+    const viewer = container.querySelector<HTMLDivElement>(
+      '[aria-label="Fullscreen image"]',
+    );
+    expect(viewer).not.toBeNull();
+
+    act(() => viewer?.click());
+    act(() =>
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })),
+    );
+
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -62,10 +62,10 @@ describe("chat Tailwind components", () => {
 
     expect(aiHtml).toContain('<button type="button"');
     expect(aiHtml).toContain(
-      'data-analytics-key="chat.open_private_zoom_from_avatar"',
+      'data-analytics-key="chat.open_private_zone_from_avatar"',
     );
     expect(aiHtml).toContain(
-      'aria-label="Open Elio Silvestri&#x27;s private zoom"',
+      'aria-label="Open Elio Silvestri&#x27;s private zone"',
     );
     expect(userHtml).toContain('<button type="button"');
     expect(userHtml).toContain(
@@ -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/chat-input-bar.tsx

@@ -17,7 +17,7 @@ import { ChatSendButton } from "./chat-send-button";
 import styles from "./chat-input-bar.module.css";
 
 const log = new Logger("AppChatComponentsChatInputBar");
-const POINTER_SEND_CLICK_DEDUPE_MS = 500;
+const POINTER_SEND_DEBOUNCE_MS = 300;
 const CHAT_ACTION_MENU_ID = "chat-composer-action-menu";
 
 export interface ChatInputBarProps {
@@ -82,7 +82,7 @@ export function ChatInputBar({ disabled = false }: ChatInputBarProps) {
   const handleSend = (source: "click" | "keyboard" | "pointerdown") => {
     if (source === "click") {
       const elapsed = Date.now() - lastPointerSendAtRef.current;
-      if (elapsed >= 0 && elapsed < POINTER_SEND_CLICK_DEDUPE_MS) {
+      if (elapsed >= 0 && elapsed < POINTER_SEND_DEBOUNCE_MS) {
         log.debug("[chat-input-bar] suppress duplicate click", {
           elapsed,
           contentLength: input.length,
@@ -115,6 +115,15 @@ export function ChatInputBar({ disabled = false }: ChatInputBarProps) {
 
   const handleMenuToggle = () => {
     if (disabled || hasContent) return;
+    const elapsed = Date.now() - lastPointerSendAtRef.current;
+    if (elapsed >= 0 && elapsed < POINTER_SEND_DEBOUNCE_MS) {
+      log.debug("[chat-input-bar] suppress post-send menu toggle", {
+        elapsed,
+        disabled,
+        isFocused,
+      });
+      return;
+    }
     if (!isActionMenuOpen) textareaRef.current?.blur();
     setIsActionMenuOpen((open) => !open);
   };

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,74 @@
   cursor: pointer;
 }
 
+.compactButton {
+  display: grid;
+  width: min(100%, 240px);
+  min-width: 0;
+  max-width: 240px;
+  min-height: 50px;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 10px;
+  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: 32px;
+  height: 32px;
+  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: 11px;
+  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: 17px;
+  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 +210,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/fullscreen-image-viewer.tsx

@@ -10,7 +10,7 @@
  *   - 双指缩放（CSS `touch-action: pinch-zoom`）
  */
 import { ChevronLeft } from "lucide-react";
-import { useEffect } from "react";
+import { useEffect, type MouseEvent } from "react";
 
 import { BackButton } from "@/app/_components";
 
@@ -44,6 +44,10 @@ export function FullscreenImageViewer({
     return () => document.removeEventListener("keydown", handleKey);
   }, [onClose]);
 
+  const handleBackdropClick = (event: MouseEvent<HTMLDivElement>) => {
+    if (event.target === event.currentTarget) onClose();
+  };
+
   if (imagePaywalled) {
     return (
       <div
@@ -90,7 +94,7 @@ export function FullscreenImageViewer({
   return (
     <div
       className={styles.viewer}
-      onClick={onClose}
+      onClick={handleBackdropClick}
       role="dialog"
       aria-modal="true"
       aria-label="Fullscreen image"
@@ -110,7 +114,7 @@ export function FullscreenImageViewer({
         errorClassName="error"
         width={800}
         height={800}
-        onClick={(event) => event.stopPropagation()}
+        onClick={onClose}
       />
     </div>
   );

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-avatar.tsx

@@ -29,8 +29,8 @@ export function MessageAvatar({
           imageSize={43}
           priority
           className={AVATAR_CLASS_NAME}
-          actionLabel={`Open ${character.displayName}'s private zoom`}
+          actionLabel={`Open ${character.displayName}'s private zone`}
-          analyticsKey="chat.open_private_zoom_from_avatar"
+          analyticsKey="chat.open_private_zone_from_avatar"
           onClick={onClick}
         />
       );

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/layout.tsx

@@ -22,8 +22,8 @@ export const metadata: Metadata = {
   },
   // iOS 触屏图标
   icons: {
-    icon: "/favicon.ico",
+    icon: "/favicon.ico?v=20260724",
-    apple: "/favicon.ico",
+    apple: "/images/icons/Icon-192.png?v=20260724",
   },
 };
 

src/app/private-zone/__tests__/private-album-gallery-url.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   buildPrivateAlbumGalleryUrl,
-  buildPrivateZoomWithoutGalleryUrl,
+  buildPrivateZoneWithoutGalleryUrl,
   getPrivateAlbumGalleryState,
 } from "../private-album-gallery-url";
 
@@ -11,7 +11,7 @@ describe("private album gallery URL", () => {
     const url = buildPrivateAlbumGalleryUrl("album:91", 3);
     const params = new URL(url, "https://cozsweet.test").searchParams;
 
-    expect(url).toBe("/private-zoom?album=album%3A91&image=3");
+    expect(url).toBe("/private-zone?album=album%3A91&image=3");
     expect(getPrivateAlbumGalleryState(params)).toEqual({
       albumId: "album:91",
       imageIndex: 3,
@@ -29,9 +29,9 @@ describe("private album gallery URL", () => {
 
   it("removes gallery params without dropping other query values", () => {
     expect(
-      buildPrivateZoomWithoutGalleryUrl(
+      buildPrivateZoneWithoutGalleryUrl(
         new URLSearchParams("album=album-1&image=2&source=external"),
       ),
-    ).toBe("/private-zoom?source=external");
+    ).toBe("/private-zone?source=external");
   });
 });

src/app/private-zone/__tests__/private-album-images.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { PrivateAlbumSchema } from "@/data/schemas/private-zoom";
+import { PrivateAlbumSchema } from "@/data/schemas/private-zone";
 
 import {
   findPrivateAlbumDisplayImage,

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

@@ -6,10 +6,10 @@ 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 { PrivateZoomEvent } from "@/stores/private-zoom";
+import type { PrivateZoneEvent } from "@/stores/private-zone";
-import type { PrivateZoomUnlockPaywallRequest } from "@/stores/private-zoom/private-zoom-state";
+import type { PrivateZoneUnlockPaywallRequest } from "@/stores/private-zone/private-zone-state";
 
-import { usePrivateZoomUnlockPaywallNavigation } from "../use-private-zoom-flow";
+import { usePrivateZoneUnlockPaywallNavigation } from "../use-private-zone-flow";
 
 const mocks = vi.hoisted(() => ({
   openAuth: vi.fn(),
@@ -30,7 +30,7 @@ vi.mock("@/lib/analytics", () => ({
   },
 }));
 
-const unlockPaywallRequest: PrivateZoomUnlockPaywallRequest = {
+const unlockPaywallRequest: PrivateZoneUnlockPaywallRequest = {
   albumId: "album-1",
   reason: "insufficient_credits",
   requiredCredits: 10,
@@ -38,7 +38,7 @@ const unlockPaywallRequest: PrivateZoomUnlockPaywallRequest = {
   shortfallCredits: 7,
 };
 
-describe("Private Zoom paywall navigation", () => {
+describe("Private Zone paywall navigation", () => {
   let container: HTMLDivElement;
   let root: Root;
 
@@ -58,31 +58,31 @@ describe("Private Zoom paywall navigation", () => {
     container.remove();
   });
 
-  it("opens top up with a private zoom return target", () => {
+  it("opens top up with a private zone return target", () => {
-    const roomDispatch = vi.fn<Dispatch<PrivateZoomEvent>>();
+    const roomDispatch = vi.fn<Dispatch<PrivateZoneEvent>>();
 
     renderHarness(root, "email", roomDispatch);
 
     expect(mocks.openSubscription).toHaveBeenCalledWith({
       type: "topup",
-      returnTo: "private-zoom",
+      returnTo: "private-zone",
       analytics: {
         entryPoint: "private_album_unlock",
         triggerReason: "insufficient_credits",
       },
     });
     expect(roomDispatch).toHaveBeenCalledWith({
-      type: "PrivateZoomUnlockPaywallConsumed",
+      type: "PrivateZoneUnlockPaywallConsumed",
     });
   });
 
-  it("keeps guest users on the private zoom auth return path", () => {
+  it("keeps guest users on the private zone auth return path", () => {
-    const roomDispatch = vi.fn<Dispatch<PrivateZoomEvent>>();
+    const roomDispatch = vi.fn<Dispatch<PrivateZoneEvent>>();
 
     renderHarness(root, "guest", roomDispatch);
 
     expect(mocks.openAuth).toHaveBeenCalledWith(
-      getCharacterRoutes("maya").privateZoom,
+      getCharacterRoutes("maya").privateZone,
     );
     expect(mocks.openSubscription).not.toHaveBeenCalled();
   });
@@ -91,7 +91,7 @@ describe("Private Zoom paywall navigation", () => {
 function renderHarness(
   root: Root,
   loginStatus: LoginStatus,
-  roomDispatch: Dispatch<PrivateZoomEvent>,
+  roomDispatch: Dispatch<PrivateZoneEvent>,
 ): void {
   const character = getCharacterBySlug("maya");
   if (!character) throw new Error("Missing Maya character fixture");
@@ -109,9 +109,9 @@ function Harness({
   roomDispatch,
 }: {
   loginStatus: LoginStatus;
-  roomDispatch: Dispatch<PrivateZoomEvent>;
+  roomDispatch: Dispatch<PrivateZoneEvent>;
 }) {
-  usePrivateZoomUnlockPaywallNavigation({
+  usePrivateZoneUnlockPaywallNavigation({
     loginStatus,
     roomDispatch,
     unlockPaywallRequest,

src/app/private-zone/__tests__/use-private-zone-flow.test.ts

@@ -1,19 +1,19 @@
 import { describe, expect, it } from "vitest";
 
-import { isPrivateZoomAuthRequired } from "../use-private-zoom-flow";
+import { isPrivateZoneAuthRequired } from "../use-private-zone-flow";
 
-describe("isPrivateZoomAuthRequired", () => {
+describe("isPrivateZoneAuthRequired", () => {
   it.each(["guest", "notLoggedIn"] as const)(
     "requires auth for %s users",
     (loginStatus) => {
-      expect(isPrivateZoomAuthRequired(loginStatus)).toBe(true);
+      expect(isPrivateZoneAuthRequired(loginStatus)).toBe(true);
     },
   );
 
   it.each(["email", "facebook", "google"] as const)(
     "allows %s users to top up directly",
     (loginStatus) => {
-      expect(isPrivateZoomAuthRequired(loginStatus)).toBe(false);
+      expect(isPrivateZoneAuthRequired(loginStatus)).toBe(false);
     },
   );
 });

src/app/private-zone/components/__tests__/private-album-card.interaction.test.tsx

@@ -4,7 +4,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { PrivateAlbumSchema } from "@/data/schemas/private-zoom";
+import { PrivateAlbumSchema } from "@/data/schemas/private-zone";
 
 import { PrivateAlbumCard } from "../private-album-card";
 
@@ -33,9 +33,9 @@ describe("PrivateAlbumCard interactions", () => {
       imageCount: 4,
       images: [
         { url: "", locked: false, index: 0 },
-        { url: "/images/private-zoom/locked.png", locked: true, index: 1 },
+        { url: "/images/private-zone/locked.png", locked: true, index: 1 },
-        { url: "/images/private-zoom/photo-2.png", locked: false, index: 2 },
+        { url: "/images/private-zone/photo-2.png", locked: false, index: 2 },
-        { url: "/images/private-zoom/photo-3.png", locked: false, index: 3 },
+        { url: "/images/private-zone/photo-3.png", locked: false, index: 3 },
       ],
       locked: false,
       unlocked: true,
@@ -72,7 +72,7 @@ describe("PrivateAlbumCard interactions", () => {
       title: "Locked afternoon",
       imageCount: 3,
       images: [
-        { url: "/images/private-zoom/locked.png", locked: true, index: 0 },
+        { url: "/images/private-zone/locked.png", locked: true, index: 0 },
       ],
       locked: true,
       unlocked: false,

src/app/private-zone/components/__tests__/private-album-card.test.tsx

@@ -5,11 +5,11 @@ import {
   PrivateAlbumSchema,
   type PrivateAlbum,
   type PrivateAlbumInput,
-} from "@/data/schemas/private-zoom";
+} from "@/data/schemas/private-zone";
 
 import { PrivateAlbumCard } from "../private-album-card";
 
-const COVER_URL = "/images/private-zoom/banner/elio.png";
+const COVER_URL = "/images/private-zone/banner/elio.png";
 
 function makeAlbum(overrides: Partial<PrivateAlbumInput> = {}): PrivateAlbum {
   return PrivateAlbumSchema.parse({
@@ -157,7 +157,7 @@ describe("PrivateAlbumCard", () => {
 
 function makeImages(count: number) {
   return Array.from({ length: count }, (_, index) => ({
-    url: `/images/private-zoom/photo-${index}.png`,
+    url: `/images/private-zone/photo-${index}.png`,
     locked: false,
     index,
   }));

src/app/private-zone/components/__tests__/private-album-gallery.test.tsx

@@ -4,7 +4,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { PrivateAlbumSchema } from "@/data/schemas/private-zoom";
+import { PrivateAlbumSchema } from "@/data/schemas/private-zone";
 
 import { PrivateAlbumGallery } from "../private-album-gallery";
 
@@ -13,11 +13,11 @@ const album = PrivateAlbumSchema.parse({
   title: "Private afternoon",
   imageCount: 5,
   images: [
-    { url: "/images/private-zoom/photo-0.png", locked: false, index: 0 },
+    { url: "/images/private-zone/photo-0.png", locked: false, index: 0 },
     { url: "", locked: false, index: 1 },
-    { url: "/images/private-zoom/locked.png", locked: true, index: 2 },
+    { url: "/images/private-zone/locked.png", locked: true, index: 2 },
-    { url: "/images/private-zoom/photo-3.png", locked: false, index: 3 },
+    { url: "/images/private-zone/photo-3.png", locked: false, index: 3 },
-    { url: "/images/private-zoom/photo-4.png", locked: false, index: 4 },
+    { url: "/images/private-zone/photo-4.png", locked: false, index: 4 },
   ],
   locked: false,
   unlocked: true,

src/app/private-zone/components/private-album-card.tsx

@@ -3,8 +3,8 @@ import Image from "next/image";
 import { Copy, ImageIcon, LockKeyhole } from "lucide-react";
 
 import { CharacterAvatar } from "@/app/_components";
-import type { PrivateAlbum } from "@/data/schemas/private-zoom";
+import type { PrivateAlbum } from "@/data/schemas/private-zone";
-import { isPrivateAlbumLocked } from "@/lib/private-zoom/private_album";
+import { isPrivateAlbumLocked } from "@/lib/private-zone/private_album";
 
 import {
   getPrivateAlbumDisplayImages,
@@ -12,7 +12,7 @@ import {
   PRIVATE_ALBUM_GRID_LIMIT,
 } from "../private-album-images";
 
-import styles from "../private-zoom-screen.module.css";
+import styles from "../private-zone-screen.module.css";
 
 export interface PrivateAlbumCardProps {
   album: PrivateAlbum;

src/app/private-zone/components/private-album-gallery.tsx

@@ -11,14 +11,14 @@ import {
 import Image from "next/image";
 import { ChevronLeft, ChevronRight, X } from "lucide-react";
 
-import type { PrivateAlbum } from "@/data/schemas/private-zoom";
+import type { PrivateAlbum } from "@/data/schemas/private-zone";
 
 import {
   getResistedGalleryDragDistance,
   resolveGallerySwipeDirection,
 } from "../private-album-gallery-motion";
 import { getPrivateAlbumDisplayImages } from "../private-album-images";
-import styles from "../private-zoom-screen.module.css";
+import styles from "../private-zone-screen.module.css";
 
 export interface PrivateAlbumGalleryProps {
   album: PrivateAlbum;

src/app/private-zone/components/status-card.tsx

@@ -1,4 +1,4 @@
-import styles from "../private-zoom-screen.module.css";
+import styles from "../private-zone-screen.module.css";
 
 export interface StatusCardProps {
   message: string;

src/app/private-zone/components/unlock-confirm-dialog.tsx

@@ -1,6 +1,6 @@
-import type { PrivateAlbum } from "@/data/schemas/private-zoom";
+import type { PrivateAlbum } from "@/data/schemas/private-zone";
 
-import styles from "../private-zoom-screen.module.css";
+import styles from "../private-zone-screen.module.css";
 
 export interface UnlockConfirmDialogProps {
   album: PrivateAlbum;

src/app/private-zone/page.tsx

@@ -7,14 +7,14 @@ import {
   type RouteSearchParams,
 } from "@/router/routes";
 
-export default async function PrivateZoomPage({
+export default async function PrivateZonePage({
   searchParams,
 }: {
   searchParams: Promise<RouteSearchParams>;
 }) {
   redirect(
     appendRouteSearchParams(
-      getCharacterRoutes(DEFAULT_CHARACTER_SLUG).privateZoom,
+      getCharacterRoutes(DEFAULT_CHARACTER_SLUG).privateZone,
       await searchParams,
     ),
   );

src/app/private-zone/private-album-gallery-url.ts

@@ -15,7 +15,7 @@ export function getPrivateAlbumGalleryState(input: {
 export function buildPrivateAlbumGalleryUrl(
   albumId: string,
   imageIndex: number,
-  basePath: string = ROUTES.privateZoom,
+  basePath: string = ROUTES.privateZone,
 ): string {
   const params = new URLSearchParams({
     [PRIVATE_ALBUM_QUERY_PARAM]: albumId,
@@ -24,9 +24,9 @@ export function buildPrivateAlbumGalleryUrl(
   return `${basePath}?${params.toString()}`;
 }
 
-export function buildPrivateZoomWithoutGalleryUrl(
+export function buildPrivateZoneWithoutGalleryUrl(
   input: { toString: () => string },
-  basePath: string = ROUTES.privateZoom,
+  basePath: string = ROUTES.privateZone,
 ): string {
   const params = new URLSearchParams(input.toString());
   params.delete(PRIVATE_ALBUM_QUERY_PARAM);

src/app/private-zone/private-album-images.ts

@@ -1,4 +1,4 @@
-import type { PrivateAlbum } from "@/data/schemas/private-zoom";
+import type { PrivateAlbum } from "@/data/schemas/private-zone";
 
 export const PRIVATE_ALBUM_GRID_LIMIT = 9;
 

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,18 +5,24 @@ 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,
   useActiveCharacterRoutes,
 } from "@/providers/character-provider";
-import { isPrivateAlbumLocked } from "@/lib/private-zoom/private_album";
+import { isPrivateAlbumLocked } from "@/lib/private-zone/private_album";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
 import {
-  usePrivateZoomDispatch,
+  usePrivateZoneDispatch,
-  usePrivateZoomState,
+  usePrivateZoneState,
-} from "@/stores/private-zoom";
+} from "@/stores/private-zone";
 
 import {
   PrivateAlbumCard,
@@ -24,21 +30,21 @@ import {
   StatusCard,
   UnlockConfirmDialog,
 } from "./components";
-import styles from "./private-zoom-screen.module.css";
+import styles from "./private-zone-screen.module.css";
 import {
-  isPrivateZoomAuthRequired,
+  isPrivateZoneAuthRequired,
-  usePrivateZoomBootstrapFlow,
+  usePrivateZoneBootstrapFlow,
-  usePrivateZoomUnlockPaywallNavigation,
+  usePrivateZoneUnlockPaywallNavigation,
-  usePrivateZoomUnlockSuccessRefresh,
+  usePrivateZoneUnlockSuccessRefresh,
-} from "./use-private-zoom-flow";
+} from "./use-private-zone-flow";
 import {
   buildPrivateAlbumGalleryUrl,
-  buildPrivateZoomWithoutGalleryUrl,
+  buildPrivateZoneWithoutGalleryUrl,
   getPrivateAlbumGalleryState,
 } from "./private-album-gallery-url";
 import { findPrivateAlbumDisplayImage } from "./private-album-images";
 
-export function PrivateZoomScreen() {
+export function PrivateZoneScreen() {
   const router = useRouter();
   const searchParams = useSearchParams();
   const navigator = useAppNavigator();
@@ -46,15 +52,15 @@ export function PrivateZoomScreen() {
   const characterRoutes = useActiveCharacterRoutes();
   const authState = useAuthState();
   const authDispatch = useAuthDispatch();
-  const state = usePrivateZoomState();
+  const state = usePrivateZoneState();
-  const dispatch = usePrivateZoomDispatch();
+  const dispatch = usePrivateZoneDispatch();
   const openedGalleryInPageRef = useRef(false);
   const galleryState = useMemo(
     () => getPrivateAlbumGalleryState(searchParams),
     [searchParams],
   );
 
-  usePrivateZoomBootstrapFlow({
+  usePrivateZoneBootstrapFlow({
     authDispatch,
     hasInitialized: authState.hasInitialized,
     isAuthLoading: authState.isLoading,
@@ -62,17 +68,17 @@ export function PrivateZoomScreen() {
     roomDispatch: dispatch,
     roomStatus: state.status,
   });
-  usePrivateZoomUnlockPaywallNavigation({
+  usePrivateZoneUnlockPaywallNavigation({
     loginStatus: authState.loginStatus,
     roomDispatch: dispatch,
     unlockPaywallRequest: state.unlockPaywallRequest,
   });
-  usePrivateZoomUnlockSuccessRefresh(state.unlockSuccessNonce);
+  usePrivateZoneUnlockSuccessRefresh(state.unlockSuccessNonce);
 
   const displayName = character.displayName;
   const avatarUrl = character.assets.avatar;
-  const title = character.copy.privateZoomTitle;
+  const title = character.copy.privateZoneTitle;
-  const subtitle = character.copy.privateZoomSubtitle;
+  const subtitle = character.copy.privateZoneSubtitle;
   const pendingAlbum = useMemo(
     () =>
       state.items.find(
@@ -107,15 +113,15 @@ export function PrivateZoomScreen() {
       !galleryImage
     ) {
       router.replace(
-        buildPrivateZoomWithoutGalleryUrl(
+        buildPrivateZoneWithoutGalleryUrl(
           searchParams,
-          characterRoutes.privateZoom,
+          characterRoutes.privateZone,
         ),
         { scroll: false },
       );
     }
   }, [
-    characterRoutes.privateZoom,
+    characterRoutes.privateZone,
     galleryAlbum,
     galleryImage,
     galleryState,
@@ -125,15 +131,15 @@ export function PrivateZoomScreen() {
   ]);
 
   const handleTopUpClick = () => {
-    if (isPrivateZoomAuthRequired(authState.loginStatus)) {
+    if (isPrivateZoneAuthRequired(authState.loginStatus)) {
-      navigator.openAuth(characterRoutes.privateZoom);
+      navigator.openAuth(characterRoutes.privateZone);
       return;
     }
     navigator.openSubscription({
       type: "topup",
-      returnTo: "private-zoom",
+      returnTo: "private-zone",
       analytics: {
-        entryPoint: "private_zoom",
+        entryPoint: "private_zone",
         triggerReason: "vip_cta",
       },
     });
@@ -145,7 +151,7 @@ export function PrivateZoomScreen() {
       buildPrivateAlbumGalleryUrl(
         albumId,
         imageIndex,
-        characterRoutes.privateZoom,
+        characterRoutes.privateZone,
       ),
       { scroll: false },
     );
@@ -158,9 +164,9 @@ export function PrivateZoomScreen() {
       return;
     }
     router.replace(
-      buildPrivateZoomWithoutGalleryUrl(
+      buildPrivateZoneWithoutGalleryUrl(
         searchParams,
-        characterRoutes.privateZoom,
+        characterRoutes.privateZone,
       ),
       { scroll: false },
     );
@@ -172,7 +178,7 @@ export function PrivateZoomScreen() {
       buildPrivateAlbumGalleryUrl(
         galleryAlbum.albumId,
         imageIndex,
-        characterRoutes.privateZoom,
+        characterRoutes.privateZone,
       ),
       { scroll: false },
     );
@@ -183,11 +189,17 @@ export function PrivateZoomScreen() {
       <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}>
             <Image
-              src={character.assets.privateZoomBanner}
+              src={character.assets.privateZoneBanner}
               alt=""
               width={2048}
               height={1152}
@@ -213,8 +225,8 @@ export function PrivateZoomScreen() {
 
           <button
             type="button"
-            data-analytics-key="private_zoom.primary_cta"
+            data-analytics-key="private_zone.primary_cta"
-            data-analytics-label="Open private zoom top up"
+            data-analytics-label="Open private zone top up"
             className={styles.primaryCta}
             onClick={handleTopUpClick}
           >
@@ -237,7 +249,7 @@ export function PrivateZoomScreen() {
             <StatusCard
               message={state.errorMessage}
               actionLabel="Retry"
-              onAction={() => dispatch({ type: "PrivateZoomRefresh" })}
+              onAction={() => dispatch({ type: "PrivateZoneRefresh" })}
             />
           ) : null}
 
@@ -245,14 +257,6 @@ export function PrivateZoomScreen() {
             <StatusCard message="Loading private albums..." />
           ) : null}
 
-          {!state.isLoading && state.items.length === 0 && !state.errorMessage ? (
-            <StatusCard
-              message="No private albums yet."
-              actionLabel="Refresh"
-              onAction={() => dispatch({ type: "PrivateZoomRefresh" })}
-            />
-          ) : null}
-
           <div className={styles.timeline}>
             {state.items.map((album, index) => (
               <PrivateAlbumCard
@@ -267,7 +271,7 @@ export function PrivateZoomScreen() {
                 }
                 onUnlock={() =>
                   dispatch({
-                    type: "PrivateZoomUnlockRequested",
+                    type: "PrivateZoneUnlockRequested",
                     albumId: album.albumId,
                   })
                 }
@@ -277,12 +281,18 @@ export function PrivateZoomScreen() {
         </section>
 
         <AppBottomNav
-          activeItem="privateZoom"
+          activeItem="privateZone"
-          privateZoomLabel={character.copy.privateZoomTitle}
+          privateZoneLabel={character.copy.privateZoneTitle}
           onChatClick={() =>
             navigator.push(characterRoutes.splash, { scroll: false })
           }
-          onPrivateZoomClick={() => undefined}
+          onPrivateZoneClick={() => undefined}
+          onMenuClick={() =>
+            navigator.push(
+              buildGlobalPageUrl(ROUTES.profile, characterRoutes.chat),
+              { scroll: false },
+            )
+          }
         />
 
         {pendingAlbum ? (
@@ -290,8 +300,8 @@ export function PrivateZoomScreen() {
             album={pendingAlbum}
             isUnlocking={state.isUnlocking}
             errorMessage={state.unlockErrorMessage}
-            onCancel={() => dispatch({ type: "PrivateZoomUnlockCancelled" })}
+            onCancel={() => dispatch({ type: "PrivateZoneUnlockCancelled" })}
-            onConfirm={() => dispatch({ type: "PrivateZoomUnlockConfirmed" })}
+            onConfirm={() => dispatch({ type: "PrivateZoneUnlockConfirmed" })}
           />
         ) : state.unlockErrorMessage ? (
           <div className={styles.toast} role="status">

src/app/private-zone/use-private-zone-flow.ts

@@ -8,37 +8,37 @@ import { behaviorAnalytics } from "@/lib/analytics";
 import { useActiveCharacterRoutes } from "@/providers/character-provider";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import type { AuthEvent } from "@/stores/auth/auth-events";
-import type { PrivateZoomEvent } from "@/stores/private-zoom";
+import type { PrivateZoneEvent } from "@/stores/private-zone";
-import type { PrivateZoomUnlockPaywallRequest } from "@/stores/private-zoom/private-zoom-state";
+import type { PrivateZoneUnlockPaywallRequest } from "@/stores/private-zone/private-zone-state";
 import { useUserDispatch } from "@/stores/user/user-context";
 
-export interface UsePrivateZoomBootstrapFlowInput {
+export interface UsePrivateZoneBootstrapFlowInput {
   authDispatch: Dispatch<AuthEvent>;
   hasInitialized: boolean;
   isAuthLoading: boolean;
   loginStatus: LoginStatus;
-  roomDispatch: Dispatch<PrivateZoomEvent>;
+  roomDispatch: Dispatch<PrivateZoneEvent>;
   roomStatus: string;
 }
 
-export interface UsePrivateZoomUnlockPaywallNavigationInput {
+export interface UsePrivateZoneUnlockPaywallNavigationInput {
   loginStatus: LoginStatus;
-  roomDispatch: Dispatch<PrivateZoomEvent>;
+  roomDispatch: Dispatch<PrivateZoneEvent>;
-  unlockPaywallRequest: PrivateZoomUnlockPaywallRequest | null;
+  unlockPaywallRequest: PrivateZoneUnlockPaywallRequest | null;
 }
 
-export function isPrivateZoomAuthRequired(loginStatus: LoginStatus): boolean {
+export function isPrivateZoneAuthRequired(loginStatus: LoginStatus): boolean {
   return loginStatus === "guest" || loginStatus === "notLoggedIn";
 }
 
-export function usePrivateZoomBootstrapFlow({
+export function usePrivateZoneBootstrapFlow({
   authDispatch,
   hasInitialized,
   isAuthLoading,
   loginStatus,
   roomDispatch,
   roomStatus,
-}: UsePrivateZoomBootstrapFlowInput): void {
+}: UsePrivateZoneBootstrapFlowInput): void {
   const previousLoginStatusRef = useRef(loginStatus);
 
   useGuestLoginBootstrap({
@@ -56,12 +56,12 @@ export function usePrivateZoomBootstrapFlow({
     previousLoginStatusRef.current = loginStatus;
 
     if (roomStatus === "idle") {
-      roomDispatch({ type: "PrivateZoomInit" });
+      roomDispatch({ type: "PrivateZoneInit" });
       return;
     }
 
     if (previousLoginStatus !== loginStatus && roomStatus !== "loading") {
-      roomDispatch({ type: "PrivateZoomRefresh" });
+      roomDispatch({ type: "PrivateZoneRefresh" });
     }
   }, [
     hasInitialized,
@@ -72,19 +72,19 @@ export function usePrivateZoomBootstrapFlow({
   ]);
 }
 
-export function usePrivateZoomUnlockPaywallNavigation({
+export function usePrivateZoneUnlockPaywallNavigation({
   loginStatus,
   roomDispatch,
   unlockPaywallRequest,
-}: UsePrivateZoomUnlockPaywallNavigationInput): void {
+}: UsePrivateZoneUnlockPaywallNavigationInput): void {
   const navigator = useAppNavigator();
   const characterRoutes = useActiveCharacterRoutes();
 
   useEffect(() => {
     if (!unlockPaywallRequest) return;
 
-    if (isPrivateZoomAuthRequired(loginStatus)) {
+    if (isPrivateZoneAuthRequired(loginStatus)) {
-      navigator.openAuth(characterRoutes.privateZoom);
+      navigator.openAuth(characterRoutes.privateZone);
     } else {
       behaviorAnalytics.paywallShown({
         entryPoint: "private_album_unlock",
@@ -92,16 +92,16 @@ export function usePrivateZoomUnlockPaywallNavigation({
       });
       navigator.openSubscription({
         type: "topup",
-        returnTo: "private-zoom",
+        returnTo: "private-zone",
         analytics: {
           entryPoint: "private_album_unlock",
           triggerReason: "insufficient_credits",
         },
       });
     }
-    roomDispatch({ type: "PrivateZoomUnlockPaywallConsumed" });
+    roomDispatch({ type: "PrivateZoneUnlockPaywallConsumed" });
   }, [
-    characterRoutes.privateZoom,
+    characterRoutes.privateZone,
     loginStatus,
     navigator,
     roomDispatch,
@@ -109,7 +109,7 @@ export function usePrivateZoomUnlockPaywallNavigation({
   ]);
 }
 
-export function usePrivateZoomUnlockSuccessRefresh(
+export function usePrivateZoneUnlockSuccessRefresh(
   unlockSuccessNonce: number,
 ): void {
   const userDispatch = useUserDispatch();

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>
   );