fix(payment): route Philippine GCash separately from QRIS

(cherry picked from commit ef9b79bc83)

.gitea/workflows/docker-image.yml

@@ -4,43 +4,12 @@ on:
   push:
     branches:
       - main
-      - test
+      - pre
   workflow_dispatch:
 
 jobs:
-  quality:
-    name: Quality and Bundle Budgets
-    runs-on: gitea-label
-    container:
-      image: cozsweet-act-runner-node24-docker:latest
-    env:
-      NEXT_TELEMETRY_DISABLED: "1"
-      SENTRY_UPLOAD_SOURCEMAPS: "0"
-
-    steps:
-      - name: Skip quality gate for test branch
-        if: ${{ github.ref == 'refs/heads/test' }}
-        run: echo "Quality gate is disabled for the test branch."
-
-      - name: Checkout
-        if: ${{ github.ref != 'refs/heads/test' }}
-        uses: actions/checkout@v4
-
-      - name: Install dependencies
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm install --frozen-lockfile
-
-      - name: Run quality checks
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm quality
-
-      - name: Enforce bundle budgets
-        if: ${{ github.ref != 'refs/heads/test' }}
-        run: pnpm perf:bundle:check
-
   publish:
     name: Build and Push Docker Image
-    needs: quality
     runs-on: gitea-label
     container:
       image: cozsweet-act-runner-node24-docker:latest
@@ -79,7 +48,7 @@ jobs:
               DEPLOY_ENV="prod"
               NEXT_ENV_FILE=".env.production"
               ;;
-            test)
+            pre)
               DEPLOY_ENV="test"
               NEXT_ENV_FILE=".env.local"
               ;;
@@ -183,12 +152,9 @@ jobs:
       - name: Deploy image over SSH
         env:
           SSH_HOST: ${{ secrets.SSH_HOST }}
-          SSH_USER: ${{ secrets.SSH_USER }}
           SSH_PORT: ${{ secrets.SSH_PORT }}
           SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
           SSH_KNOWN_HOSTS: ${{ secrets.SSH_KNOWN_HOSTS }}
-          TEST_DEPLOY_DIR: ${{ secrets.TEST_DEPLOY_DIR }}
-          PROD_DEPLOY_DIR: ${{ secrets.PROD_DEPLOY_DIR }}
           REGISTRY_HOST: ${{ secrets.REGISTRY_HOST }}
           REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
           REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
@@ -197,16 +163,18 @@ jobs:
 
           case "$DEPLOY_ENV" in
             test)
-              DEPLOY_DIR="${TEST_DEPLOY_DIR:-/opt/cozsweet-web-test}"
+              DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-test"
               HOST_PORT="9135"
               CONTAINER_NAME="cozsweet-web-test"
               PROJECT_NAME="cozsweet-web-test"
+              SERVER_RETAIN_COUNT="1"
               ;;
             prod)
-              DEPLOY_DIR="${PROD_DEPLOY_DIR:-/opt/cozsweet-web-prod}"
+              DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-prod"
               HOST_PORT="9185"
               CONTAINER_NAME="cozsweet-web-prod"
               PROJECT_NAME="cozsweet-web-prod"
+              SERVER_RETAIN_COUNT="2"
               ;;
             *)
               echo "Unsupported deploy env: $DEPLOY_ENV" >&2
@@ -214,8 +182,11 @@ jobs:
               ;;
           esac
 
+          DEPLOY_DIR="$DEPLOY_ROOT/current"
+          DEPLOY_SHARED_DIR="$DEPLOY_ROOT/shared"
+          REMOTE_ENV_FILE="$DEPLOY_SHARED_DIR/$NEXT_ENV_FILE"
           DEPLOY_HOST="$SSH_HOST"
-          DEPLOY_USER="$SSH_USER"
+          DEPLOY_USER="lzf"
           DEPLOY_PORT="${SSH_PORT:-22}"
           DEPLOY_KEY="$SSH_PRIVATE_KEY"
           DEPLOY_KNOWN_HOSTS="$SSH_KNOWN_HOSTS"
@@ -241,19 +212,19 @@ jobs:
           SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o IdentitiesOnly=yes"
           SCP_OPTS="-i $KEY_FILE -P $DEPLOY_PORT -o IdentitiesOnly=yes"
 
-          ssh $SSH_OPTS "$SSH_TARGET" "mkdir -p '$DEPLOY_DIR'"
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "mkdir -p '$DEPLOY_DIR' '$DEPLOY_SHARED_DIR' '$DEPLOY_ROOT/releases' '$DEPLOY_ROOT/backups' '$DEPLOY_ROOT/tmp' && chmod 700 '$DEPLOY_SHARED_DIR'"
           scp $SCP_OPTS docker-compose.yml "$SSH_TARGET:$DEPLOY_DIR/docker-compose.yml"
           scp $SCP_OPTS scripts/server/deploy-docker-image.sh "$SSH_TARGET:$DEPLOY_DIR/deploy-docker-image.sh"
-          scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$DEPLOY_DIR/$NEXT_ENV_FILE"
+          scp $SCP_OPTS "$NEXT_ENV_FILE" "$SSH_TARGET:$REMOTE_ENV_FILE"
+          ssh $SSH_OPTS "$SSH_TARGET" "chmod 600 '$REMOTE_ENV_FILE'"
 
           printf '%s' "$REGISTRY_PASSWORD" \
             | ssh $SSH_OPTS "$SSH_TARGET" \
                 "docker login '$REGISTRY_HOST' -u '$REGISTRY_USERNAME' --password-stdin"
 
-          SERVER_RETAIN_COUNT="1"
-
           ssh $SSH_OPTS "$SSH_TARGET" \
-            "cd '$DEPLOY_DIR' && chmod +x ./deploy-docker-image.sh && ./deploy-docker-image.sh '$IMAGE_VERSION_TAG' '$NEXT_ENV_FILE' '$HOST_PORT' '$CONTAINER_NAME' '$PROJECT_NAME' '$SERVER_RETAIN_COUNT'"
+            "cd '$DEPLOY_DIR' && chmod +x ./deploy-docker-image.sh && ./deploy-docker-image.sh '$IMAGE_VERSION_TAG' '$REMOTE_ENV_FILE' '$HOST_PORT' '$CONTAINER_NAME' '$PROJECT_NAME' '$SERVER_RETAIN_COUNT'"
 
       - name: Purge Cloudflare cache
         env:

.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 \
-  && corepack prepare pnpm@10.30.3 --activate \
-  && pnpm config set store-dir "$PNPM_STORE_PATH"
+  && npm install --global "pnpm@10.30.3" --registry="$NPM_REGISTRY" \
+  && 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-room",
-    "./src/data/schemas/private-room/request",
-    "./src/data/schemas/private-room/response",
+    "./src/data/schemas/private-zone",
+    "./src/data/schemas/private-zone/request",
+    "./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 能力。`privateRoom` 只有在本地能力和服务端 `privateContent` 同时开启时可用。
+服务端目录决定角色是否可聊天及排序；本地目录继续提供 slug、图片、文案和 Tip 能力。`privateZone` 只有在本地能力和服务端 `privateContent` 同时开启时可用。
 
 远端目录返回前，生产环境只使用 Elio 作为临时目录；非生产环境可使用完整本地目录。远端目录加载成功后，以合并结果为准。
 
@@ -72,7 +72,7 @@ Authorization: Bearer <TOKEN>
 ```text
 /characters/{slug}/splash
 /characters/{slug}/chat
-/characters/{slug}/private-room
+/characters/{slug}/private-zone
 /characters/{slug}/tip
 ```
 
@@ -81,11 +81,11 @@ Authorization: Bearer <TOKEN>
 ```text
 /splash       -> /characters/elio/splash
 /chat         -> /characters/elio/chat
-/private-room -> /characters/elio/private-room
+/private-zone -> /characters/elio/private-zone
 /tip          -> /characters/elio/tip
 ```
 
-Chat Provider 以 `characterId` 为边界，路由角色变化时创建新的 Actor。Private Room 的角色边界由 [Private Room 权威协议](./FRONTEND_PRIVATE_ROOM_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 Room 的相册、解锁、Gallery 和支付回跳由 [Private Room 权威协议](./FRONTEND_PRIVATE_ROOM_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-room | sidebar（可选）
+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-room` 的最终页面行为由 [Private Room 权威协议](./FRONTEND_PRIVATE_ROOM_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 Room 权威协议
+# CozSweet Private Zone 权威协议
 
 ## 1. 状态与范围
 
@@ -9,11 +9,11 @@
 | 边界 | 实现位置 |
 | --- | --- |
 | API 路径与方法 | `src/data/services/api/api_contract.json` |
-| 请求与响应字段 | `src/data/schemas/private-room` |
-| API 与 Repository | `src/data/services/api/private_room_api.ts`、`src/data/repositories/private_room_repository.ts` |
-| Private Room 状态机 | `src/stores/private-room` |
-| 页面、Gallery 与导航 | `src/app/private-room` |
-| 角色 Provider | `src/providers/private-room-route-provider.tsx` |
+| 请求与响应字段 | `src/data/schemas/private-zone` |
+| API 与 Repository | `src/data/services/api/private_zone_api.ts`、`src/data/repositories/private_zone_repository.ts` |
+| Private Zone 状态机 | `src/stores/private-zone` |
+| 页面、Gallery 与导航 | `src/app/private-zone` |
+| 角色 Provider | `src/providers/private-zone-route-provider.tsx` |
 
 修改上述实现时必须在同一变更中更新本文，不能再新增按相册列表、解锁或 Gallery 拆分的并行协议。
 
@@ -22,13 +22,13 @@
 标准路由：
 
 ```text
-/characters/{characterSlug}/private-room
+/characters/{characterSlug}/private-zone
 ```
 
 旧地址保留为默认角色重定向，并保留查询参数：
 
 ```text
-/private-room -> /characters/elio/private-room
+/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.privateRoom=true`。该能力由本地配置和角色目录响应的 `privateContent` 共同决定；能力关闭或 slug 未知时路由返回 Not Found。
+角色必须同时存在于本地目录且 `capabilities.privateZone=true`。该能力由本地配置和角色目录响应的 `privateContent` 共同决定；能力关闭或 slug 未知时路由返回 Not Found。
 
-`PrivateRoomProvider` 以 `characterId` 为输入和 React key。切换角色会销毁旧 Actor 并创建空状态，不能复用上一角色的相册、余额或解锁请求。
+`PrivateZoneProvider` 以 `characterId` 为输入和 React key。切换角色会销毁旧 Actor 并创建空状态，不能复用上一角色的相册、余额或解锁请求。
 
 ## 3. 相册列表
 
 ```http
-GET <API_BASE_URL>/api/private-room/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 Room 分页，也不把相册列表写入本地缓存。初始化、手动刷新或登录身份变化时重新请求网络。
+前端当前只加载第一页，不实现 Private Zone 分页，也不把相册列表写入本地缓存。初始化、手动刷新或登录身份变化时重新请求网络。
 
 标准响应数据：
 
@@ -105,7 +105,7 @@ album.locked || !album.unlocked || album.lockDetail.locked
 用户点击锁定相册后，前端先展示确认 Dialog。只有待确认 `albumId` 仍存在于当前 Actor 的 `items` 中，才会发起请求。
 
 ```http
-POST <API_BASE_URL>/api/private-room/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 Room 初始化会复用 Guest 登录引导。Auth 尚未初始化或正在加载时不请求列表；`notLoggedIn` 完成 Guest bootstrap 后再进入列表加载。Guest 和正式用户都可以读取后端允许的相册列表。
+Private Zone 初始化会复用 Guest 登录引导。Auth 尚未初始化或正在加载时不请求列表；`notLoggedIn` 完成 Guest bootstrap 后再进入列表加载。Guest 和正式用户都可以读取后端允许的相册列表。
 
 积分不足生成 Paywall 请求后：
 
 | 当前身份 | 导航 |
 | --- | --- |
-| Guest 或 Not Logged In | 打开 Auth，redirect 为当前角色 Private Room |
-| 已认证用户 | 打开 Top-up，`returnTo=private-room`，保留当前角色来源 |
+| Guest 或 Not Logged In | 打开 Auth，redirect 为当前角色 Private Zone |
+| 已认证用户 | 打开 Top-up，`returnTo=private-zone`，保留当前角色来源 |
 
 Paywall 导航发起后立即消费当前请求，避免 React 重渲染重复导航。支付回跳和订单恢复遵循 [Payment 权威协议](./FRONTEND_PAYMENT_API.md)。
 
-解锁成功后 `unlockSuccessNonce` 递增，页面桥接到 `UserFetch`，刷新当前积分和权益。Private Room 不自行修改 User Store 余额。
+解锁成功后 `unlockSuccessNonce` 递增，页面桥接到 `UserFetch`，刷新当前积分和权益。Private Zone 不自行修改 User Store 余额。
 
 ## 6. Gallery URL 协议
 
 解锁相册使用查询参数打开页内 Gallery：
 
 ```text
-/characters/{slug}/private-room?album={albumId}&image={zeroBasedIndex}
+/characters/{slug}/private-zone?album={albumId}&image={zeroBasedIndex}
 ```
 
 解析规则：
@@ -208,25 +208,31 @@ Paywall 导航发起后立即消费当前请求，避免 React 重渲染重复
 
 任一条件不满足时，页面通过 replace 删除 `album` 和 `image`，并保留其他查询参数。
 
-页面内点击打开 Gallery 时，关闭操作优先使用浏览器 back；直接刷新或外部分享 Gallery URL 时，关闭操作使用 replace 返回当前角色 Private Room。键盘 Escape 关闭，左右方向键和横向滑动切换图片。
+页面内点击九宫格缩略图时，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` 下取消吸附过渡。
 
 ## 7. UI 与数据边界
 
 - React key 使用稳定 `albumId`；
 - 卡片图片数量优先使用 `imageCount`，为 0 时回退到 `images.length`；
-- Gallery 只渲染当前索引存在 URL 的图片；
+- 锁定相册显示模糊封面、角色头像、锁标识、图片数量和 `View collection` 入口；卡片不展示视频数量或积分价格，解锁价格只在确认 Dialog 中展示；
+- 解锁相册过滤锁定或空 URL 图片，并保留剩余图片的原始数组索引；
+- 1 张图片显示 4:5 大图，2/4 张使用两列，其余使用三列正方形九宫格；
+- 超过 9 张时卡片显示前九张，末格显示 `+N`，Gallery 仍可浏览全部有效图片；
+- Gallery 只挂载当前图片和相邻图片，避免多图相册同时解码全部原图；
 - `creditBalance` 是当前列表/解锁响应快照，不替代 User Store 权益；
-- Private Room 不使用 Chat 的 `conversationKey`、消息缓存或媒体缓存；
-- Private Room 不持有 Payment Actor，Top-up 通过路由级导航进入独立 Payment Provider。
+- Private Zone 不使用 Chat 的 `conversationKey`、消息缓存或媒体缓存；
+- Private Zone 不持有 Payment Actor，Top-up 通过路由级导航进入独立 Payment Provider。
 
 ## 8. 变更验收
 
-Private Room 协议相关变更至少验证：
+Private Zone 协议相关变更至少验证：
 
-1. `src/data/schemas/private-room/__tests__`；
-2. `src/data/services/api/__tests__/multi_character_api.test.ts` 中的 Private Room 请求；
-3. `src/stores/private-room/__tests__`；
-4. `src/app/private-room/__tests__` 与组件测试；
+1. `src/data/schemas/private-zone/__tests__`；
+2. `src/data/services/api/__tests__/multi_character_api.test.ts` 中的 Private Zone 请求；
+3. `src/stores/private-zone/__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/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
+| `.gitea/workflows/ci.yml` | `dev`、`main`、`pre` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
+| `.gitea/workflows/docker-image.yml` | `main`、`pre` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
 
 这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。
 
-`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`test`
-分支为快速部署测试环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
+`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`pre`
+分支用于快速部署预发环境，会跳过完整质量检查，但仍必须通过 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-room` | 指定进入的页面；不传或值无效时进入聊天页。 |
+| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。历史值 `private-room` 兼容进入 `private-zone`，新链接不得继续使用。 |
 | `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
 | `psid` | string | 传入 Facebook Page-scoped User ID。 |
 | `mode` | `promotion` | 开启聊天促销模式。 |
@@ -27,6 +27,8 @@ https://<APP_HOST>/external-entry?<参数>
 
 `mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
 
+标准私密空间参数是 `target=private-zone`。前端仅为已经发布的旧链接保留 `target=private-room` 兼容；`private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
+
 ## PSID 与登录状态流程
 
 PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
@@ -78,15 +80,18 @@ https://<APP_HOST>/external-entry?target=tip
 私密空间：
 
 ```text
-https://<APP_HOST>/external-entry?target=private-room
+https://<APP_HOST>/external-entry?target=private-zone
 ```
 
 进入 Nayeli 私密空间：
 
 ```text
-https://<APP_HOST>/external-entry?target=private-room&character=nayeli
+https://<APP_HOST>/external-entry?target=private-zone&character=nayeli
 ```
 
 `psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
 
-测试环境和正式环境的完整可点击示例见 [外部入口链接清单](./links.md)。
+完整可点击示例：
+
+- [本地调试链接清单](./debug-links.md)
+- [测试环境和正式环境链接清单](./links.md)

docs/external-entry/debug-links.md

@@ -0,0 +1,47 @@
+# 外部入口本地调试链接清单
+
+[返回外部入口接入说明](./README.md)
+
+启动本地应用后，可以直接点击以下链接进行调试。根网址为 `http://localhost:3000`，PSID 示例统一使用 `27511427698460020`。
+
+## 默认入口
+
+| 入口 | 链接 |
+| --- | --- |
+| 默认入口（Elio 聊天） | [打开默认入口](http://localhost:3000/external-entry) |
+| 普通聊天 | [打开普通聊天](http://localhost:3000/external-entry?target=chat) |
+| 携带 PSID 的聊天 | [打开 PSID 聊天示例](http://localhost:3000/external-entry?target=chat&psid=27511427698460020) |
+
+## 角色聊天
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 聊天](http://localhost:3000/external-entry?target=chat&character=elio) |
+| Maya | [打开 Maya 聊天](http://localhost:3000/external-entry?target=chat&character=maya) |
+| Nayeli | [打开 Nayeli 聊天](http://localhost:3000/external-entry?target=chat&character=nayeli) |
+
+## 聊天促销
+
+| 促销类型 | 链接 |
+| --- | --- |
+| 语音促销 | [打开语音促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=voice) |
+| 图片促销 | [打开图片促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=image) |
+| 私密文本促销 | [打开私密文本促销](http://localhost:3000/external-entry?target=chat&mode=promotion&promotion_type=private) |
+
+## 咖啡打赏
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=elio) |
+| Maya | [打开 Maya 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=maya) |
+| Nayeli | [打开 Nayeli 咖啡打赏](http://localhost:3000/external-entry?target=tip&character=nayeli) |
+
+## 私密空间
+
+| 角色 | 链接 |
+| --- | --- |
+| Elio | [打开 Elio 私密空间](http://localhost:3000/external-entry?target=private-zone&character=elio) |
+| Maya | [打开 Maya 私密空间](http://localhost:3000/external-entry?target=private-zone&character=maya) |
+| Nayeli | [打开 Nayeli 私密空间](http://localhost:3000/external-entry?target=private-zone&character=nayeli) |
+
+如需为其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。对于不带查询参数的默认入口，请改为追加 `?psid=27511427698460020`。

docs/external-entry/links.md

@@ -1,43 +1,66 @@
 # 外部入口链接清单
 
-[返回外部入口接入说明](./README.md)
+这份清单可以独立发送和直接点击。所有新链接统一使用标准参数 `target=private-zone`；历史参数 `target=private-room` 仅用于兼容已经发出的旧链接。
 
-以下链接可以直接点击打开。PSID 示例统一使用 `27511427698460020`。
+## 使用规则
+
+- `target=chat`：进入聊天页。
+- `target=tip`：进入对应角色的打赏页。
+- `target=private-zone`：进入对应角色的私密空间。
+- `character` 可使用 `elio`、`maya`、`nayeli`；不传或值无效时使用 Elio。
+- `mode=promotion` 只在 `target=chat` 且 `promotion_type` 为 `voice`、`image` 或 `private` 时生效。
+- PSID 示例统一使用 `27511427698460020`；不要在入口中放登录 Token、Page Access Token 或 App Secret。
 
 ## 测试环境
 
-| 入口 | 链接 |
-| --- | --- |
-| 普通聊天 | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) |
-| Maya 聊天 | [打开 Maya 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=maya) |
-| Nayeli 聊天 | [打开 Nayeli 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=nayeli) |
-| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) |
-| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-| 咖啡打赏 | [打开咖啡打赏](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-room) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=nayeli) |
+| 入口 | 可点击链接 | 预期落地页面 |
+| --- | --- | --- |
+| 普通聊天（Elio） | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) | `/characters/elio/chat` |
+| Maya 聊天 | [打开 Maya 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=maya) | `/characters/maya/chat` |
+| Nayeli 聊天 | [打开 Nayeli 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=nayeli) | `/characters/nayeli/chat` |
+| 携带 PSID 的 Elio 聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) | `/characters/elio/chat` |
+| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) | `/characters/elio/chat`，保存语音促销意图 |
+| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) | `/characters/elio/chat`，保存图片促销意图 |
+| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) | `/characters/elio/chat`，保存私密文本促销意图 |
+| Elio 咖啡打赏 | [打开 Elio 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=elio) | `/characters/elio/tip` |
+| Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=maya) | `/characters/maya/tip` |
+| Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=nayeli) | `/characters/nayeli/tip` |
+| Elio 私密空间 | [打开 Elio 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=elio) | `/characters/elio/private-zone` |
+| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=maya) | `/characters/maya/private-zone` |
+| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=nayeli) | `/characters/nayeli/private-zone` |
+
+## 旧链接兼容验证
+
+以下链接仅用于验证已经发出的 `private-room` 旧链接仍能正确进入私密空间。新投放链接不要再使用这些地址。
+
+| 旧入口 | 可点击链接 | 预期落地页面 |
+| --- | --- | --- |
+| Elio 旧私密空间 | [验证 Elio 旧链接](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=elio) | `/characters/elio/private-zone` |
+| Maya 旧私密空间 | [验证 Maya 旧链接](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=maya) | `/characters/maya/private-zone` |
+| Nayeli 旧私密空间 | [验证 Nayeli 旧链接](https://frontend-test.banlv-ai.com/external-entry?target=private-room&character=nayeli) | `/characters/nayeli/private-zone` |
 
 ## 正式环境
 
-| 入口 | 链接 |
-| --- | --- |
-| 普通聊天 | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) |
-| Maya 聊天 | [打开 Maya 聊天](https://cozsweet.com/external-entry?target=chat&character=maya) |
-| Nayeli 聊天 | [打开 Nayeli 聊天](https://cozsweet.com/external-entry?target=chat&character=nayeli) |
-| 携带 PSID 的聊天 | [打开 PSID 聊天示例](https://cozsweet.com/external-entry?target=chat&psid=27511427698460020) |
-| 语音促销 | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) |
-| 图片促销 | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) |
-| 私密文本促销 | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) |
-| 咖啡打赏 | [打开咖啡打赏](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-room) |
-| Maya 私密空间 | [打开 Maya 私密空间](https://cozsweet.com/external-entry?target=private-room&character=maya) |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://cozsweet.com/external-entry?target=private-room&character=nayeli) |
+正式环境仅列标准链接，不再传播 `private-room` 旧参数。
 
-如需在其他入口携带 PSID，在链接末尾追加 `&psid=27511427698460020`。
+| 入口 | 可点击链接 | 预期落地页面 |
+| --- | --- | --- |
+| 普通聊天（Elio） | [打开普通聊天](https://cozsweet.com/external-entry?target=chat) | `/characters/elio/chat` |
+| Maya 聊天 | [打开 Maya 聊天](https://cozsweet.com/external-entry?target=chat&character=maya) | `/characters/maya/chat` |
+| Nayeli 聊天 | [打开 Nayeli 聊天](https://cozsweet.com/external-entry?target=chat&character=nayeli) | `/characters/nayeli/chat` |
+| 携带 PSID 的 Elio 聊天 | [打开 PSID 聊天示例](https://cozsweet.com/external-entry?target=chat&psid=27511427698460020) | `/characters/elio/chat` |
+| 语音促销 | [打开语音促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=voice) | `/characters/elio/chat`，保存语音促销意图 |
+| 图片促销 | [打开图片促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=image) | `/characters/elio/chat`，保存图片促销意图 |
+| 私密文本促销 | [打开私密文本促销](https://cozsweet.com/external-entry?target=chat&mode=promotion&promotion_type=private) | `/characters/elio/chat`，保存私密文本促销意图 |
+| Elio 咖啡打赏 | [打开 Elio 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=elio) | `/characters/elio/tip` |
+| Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=maya) | `/characters/maya/tip` |
+| Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://cozsweet.com/external-entry?target=tip&character=nayeli) | `/characters/nayeli/tip` |
+| Elio 私密空间 | [打开 Elio 私密空间](https://cozsweet.com/external-entry?target=private-zone&character=elio) | `/characters/elio/private-zone` |
+| Maya 私密空间 | [打开 Maya 私密空间](https://cozsweet.com/external-entry?target=private-zone&character=maya) | `/characters/maya/private-zone` |
+| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://cozsweet.com/external-entry?target=private-zone&character=nayeli) | `/characters/nayeli/private-zone` |
+
+## 验收判断
+
+打开入口后，浏览器地址最终应与“预期落地页面”一致。普通聊天和私密空间必须分别落在 `/chat` 与 `/private-zone`，不能再进入同一个页面。
+
+如需在其他入口携带 PSID，在已有查询参数的链接末尾追加 `&psid=27511427698460020`。

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

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

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
-on every pull request and `dev` / `test` / `main` push.
+refresh and paid-image unlock paths with the Pixel 7 profile. CI 在所有 pull
+request 以及 `dev` / `pre` / `main` push 时运行这一层测试。
 
 ## Environment overrides
 
@@ -40,6 +40,6 @@ pnpm test:e2e:real
 
 ```bash
 PLAYWRIGHT_BASE_URL=https://cozsweet.com \
-E2E_API_BASE_URL=https://proapi.banlv-ai.com \
+E2E_API_BASE_URL=https://api.banlv-ai.com \
 pnpm test:e2e:prod
 ```

e2e/fixtures/api-mocks.ts

@@ -12,7 +12,8 @@ export interface MockCoreApisOptions {
   paidImageFlow?: boolean;
   paidImageInsufficientCreditsFlow?: boolean;
   paidVoiceInsufficientCreditsFlow?: boolean;
-  psidLoginFlow?: boolean;
+  topUpHandoffFlow?: boolean;
+  checkoutHandoffFlow?: boolean;
 }
 
 export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}) {
@@ -22,14 +23,16 @@ export async function mockCoreApis(page: Page, options: MockCoreApisOptions = {}
     paidImageFlow: options.paidImageFlow ?? false,
     paidImageInsufficientCreditsFlow: options.paidImageInsufficientCreditsFlow ?? false,
     paidVoiceInsufficientCreditsFlow: options.paidVoiceInsufficientCreditsFlow ?? false,
-    psidLoginFlow: options.psidLoginFlow ?? false,
+    topUpHandoffFlow: options.topUpHandoffFlow ?? false,
+    checkoutHandoffFlow: options.checkoutHandoffFlow ?? false,
   };
   const chatState = { hasExpiredChatSend: false, paidImageRequested: false, paidImageUnlocked: false };
 
   await registerAuthMocks(page, {
     chatSendTokenRefreshFlow: chatOptions.chatSendTokenRefreshFlow,
     isChatSendTokenExpired: () => chatState.hasExpiredChatSend,
-    psidLoginFlow: chatOptions.psidLoginFlow,
+    topUpHandoffFlow: chatOptions.topUpHandoffFlow,
+    checkoutHandoffFlow: chatOptions.checkoutHandoffFlow,
   });
   await registerCharacterMocks(page);
   await registerUserMocks(page);

e2e/fixtures/api/auth.ts

@@ -1,22 +1,30 @@
 import type { Page } from "@playwright/test";
 
 import { apiEnvelope } from "../data/common";
-import { emailLoginResponse, guestLoginResponse, psidLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse } from "../data/auth";
+import { checkoutHandoffResponse, emailLoginResponse, guestLoginResponse, refreshedEmailLoginResponse, refreshedGuestLoginResponse, topUpHandoffResponse } from "../data/auth";
 
 export interface AuthMockState {
   chatSendTokenRefreshFlow: boolean;
   isChatSendTokenExpired: () => boolean;
-  psidLoginFlow: boolean;
+  topUpHandoffFlow: boolean;
+  checkoutHandoffFlow: boolean;
 }
 
 export async function registerAuthMocks(page: Page, state: AuthMockState) {
-  await page.route("**/api/auth/login/facebook/psid", async (route) => {
-    if (!state.psidLoginFlow) {
+  await page.route("**/api/auth/handoff/checkout/consume", async (route) => {
+    if (!state.checkoutHandoffFlow) {
       await route.continue();
       return;
     }
+    await route.fulfill({ json: apiEnvelope(checkoutHandoffResponse) });
+  });
 
-    await route.fulfill({ json: apiEnvelope(psidLoginResponse) });
+  await page.route("**/api/auth/handoff/topup/consume", async (route) => {
+    if (!state.topUpHandoffFlow) {
+      await route.continue();
+      return;
+    }
+    await route.fulfill({ json: apiEnvelope(topUpHandoffResponse) });
   });
 
   await page.route("**/api/auth/guest", async (route) => {

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,35 @@ 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("discount offer test")
+      ? {
+          ...chatSendResponse,
+          reply: "I know you're thinking carefully about the price.",
+          messageId: "discount-action-message",
+          commercialAction: {
+            actionId: "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
+            type: "discountOffer",
+            copy: "Want me to ask for my best private offer?",
+            ctaLabel: "Yes, ask for me",
+            target: "discountConsent",
+            ruleId: "discount_after_price_objection",
+          },
+        }
+      : 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/fixtures/api/payment.ts

@@ -4,6 +4,16 @@ import { apiEnvelope } from "../data/common";
 import { createPaymentOrderResponse, paidPaymentOrderStatusResponse, paymentPlansResponse, tipPaymentPlansResponse, vipStatusResponse } from "../data/payment";
 
 export async function registerPaymentMocks(page: Page) {
+  await page.route("**/api/payment/commercial-offers/*/accept", async (route) => route.fulfill({ json: apiEnvelope({
+    commercialOfferId: "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
+    planId: "vip_annual",
+    subscriptionType: "vip",
+    discountPercent: 30,
+    pricePercent: 70,
+    expiresAt: "2026-07-24T08:00:00+00:00",
+    message: "I got it for you.",
+    promotionType: "commercial_seven_discount",
+  }) }));
   await page.route("**/api/payment/plans**", async (route) => route.fulfill({ json: apiEnvelope(paymentPlansResponse) }));
   await page.route("**/api/payment/tip-plans**", async (route) => route.fulfill({ json: apiEnvelope(tipPaymentPlansResponse) }));
   await page.route("**/api/payment/create-order", async (route) => route.fulfill({ json: apiEnvelope(createPaymentOrderResponse) }));

e2e/fixtures/data/auth.ts

@@ -50,14 +50,28 @@ export const refreshedEmailLoginResponse = {
   refreshToken: "e2e-refreshed-email-refresh-token",
 };
 
-export const psidLoginResponse = {
-  token: "e2e-psid-guest-token",
-  refreshToken: "",
-  matchedBy: "psid",
-  fbAsid: "",
-  fbPsid: "e2e-facebook-psid",
-  hasCompleteFacebookIdentity: false,
-  isGuest: true,
-  user: e2eUser,
-  userId: e2eUser.id,
+export const topUpHandoffResponse = {
+  token: "e2e-messenger-token",
+  refreshToken: "e2e-messenger-refresh-token",
+  loginStatus: "facebookMessenger",
+  merged: false,
+  user: {
+    ...e2eEmailUser,
+    id: "user_e2e_messenger",
+    username: "E2E Messenger User",
+    email: "messenger_hash@messenger.cozsweet.invalid",
+    loginProvider: "facebook_messenger",
+  },
+};
+
+export const checkoutHandoffResponse = {
+  token: "e2e-checkout-token",
+  refreshToken: "e2e-checkout-refresh-token",
+  loginStatus: "email",
+  user: e2eEmailUser,
+  checkoutIntent: {
+    planId: "vip_monthly",
+    autoRenew: true,
+    commercialOfferId: "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
+  },
 };

e2e/fixtures/data/chat.ts

@@ -66,6 +66,7 @@ export function createWeeklyLimitChatSendResponse(
 }
 
 export const paidImageMessageId = "msg_photo_paywall_001";
+export const paidImageDisplayMessageId = `server:${paidImageMessageId}:assistant`;
 export const paidImageUrl =
   "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=";
 export const paidImageChatSendResponse = {
@@ -74,13 +75,13 @@ export const paidImageChatSendResponse = {
   messageId: paidImageMessageId,
   isGuest: true,
   timestamp: 1_782_180_725_000,
-  image: { type: "elio_schedule", url: paidImageUrl },
+  image: { type: "elio_schedule", url: null },
   lockDetail: { locked: true, showContent: true, showUpgrade: true, reason: "image", hint: "Activate VIP to unlock the full photo.", detail: null },
 };
 
 export function createPaidImageHistoryResponse(unlocked: boolean) {
   return {
-    messages: [{ role: "assistant", type: "image", content: unlocked ? "" : paidImageChatSendResponse.reply, id: paidImageMessageId, created_at: "2026-06-30T00:00:00.000Z", audioUrl: null, image: { type: "elio_schedule", url: paidImageUrl }, lockDetail: unlocked ? { locked: false, showContent: true, showUpgrade: false, reason: null, hint: null, detail: null } : paidImageChatSendResponse.lockDetail }],
+    messages: [{ role: "assistant", type: "image", content: unlocked ? "" : paidImageChatSendResponse.reply, id: paidImageMessageId, created_at: "2026-06-30T00:00:00.000Z", audioUrl: null, image: { type: "elio_schedule", url: unlocked ? paidImageUrl : null }, lockDetail: unlocked ? { locked: false, showContent: true, showUpgrade: false, reason: null, hint: null, detail: null } : paidImageChatSendResponse.lockDetail }],
     total: 1, limit: 50, offset: 0, isVip: unlocked, privateFreeLimit: 0, privateUsedToday: 0, privateCanViewFree: false,
   };
 }

e2e/fixtures/helpers/auth.ts

@@ -11,7 +11,7 @@ export const splashStartChatButtonName = "Start Chatting";
 export const defaultCharacterSlug = "elio";
 export const defaultCharacterSplashPath = `/characters/${defaultCharacterSlug}/splash`;
 export const defaultCharacterChatPath = `/characters/${defaultCharacterSlug}/chat`;
-export const defaultCharacterSidebarPath = `/sidebar?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`;
+export const defaultCharacterProfilePath = `/profile?returnTo=%2Fcharacters%2F${defaultCharacterSlug}%2Fchat`;
 export const defaultCharacterChatUrl = new RegExp(
   `/characters/${defaultCharacterSlug}/chat(?:\\?.*)?$`,
 );

e2e/fixtures/helpers/chat.ts

@@ -27,7 +27,7 @@ export async function enterChatFromSplash(page: Page, options: { expectedUrl?: R
   await expect(startChatButton).toBeVisible({ timeout });
   await expect(startChatButton).toBeEnabled();
   for (let attempt = 0; attempt < 3; attempt += 1) {
-    await startChatButton.click();
+    await startChatButton.click({ timeout: 3_000 }).catch(() => {});
     try { await expect(page).toHaveURL(expectedUrl, { timeout: 3_000 }); return; } catch { await page.waitForTimeout(500); }
   }
   await expect(page).toHaveURL(expectedUrl, { timeout });
@@ -42,9 +42,7 @@ export async function dismissChatInterruptions(page: Page) {
 
 export async function signInWithEmailAndOpenChat(page: Page) {
   await seedEmailSession(page);
-  const historyResponsePromise = page.waitForResponse("**/api/chat/history**");
   await page.goto(defaultCharacterChatPath);
-  await historyResponsePromise;
   await dismissChatInterruptions(page);
   await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({ timeout: 20_000 });
 }

e2e/fixtures/helpers/payment.ts

@@ -1,9 +1,18 @@
 import { expect, type Page } from "@playwright/test";
 
 export async function completeVipPayment(page: Page) {
+  const checkoutButton = page.getByRole("button", { name: "Pay and Top Up" });
+  await expect(checkoutButton).toBeEnabled();
+
+  await checkoutButton.click();
+  const renewalDialog = page.getByRole("dialog", {
+    name: "Automatic Renewal Confirmation",
+  });
+  await expect(renewalDialog).toBeVisible();
+
   const createOrderRequestPromise = page.waitForRequest("**/api/payment/create-order");
   const orderStatusRequestPromise = page.waitForRequest("**/api/payment/order-status**");
-  await page.getByRole("button", { name: /Pay and Activ/i }).click();
+  await renewalDialog.getByRole("button", { name: "Confirm" }).click();
   const createOrderRequest = await createOrderRequestPromise;
   expect(createOrderRequest.postDataJSON()).toMatchObject({ planId: "vip_monthly", payChannel: "stripe" });
   await orderStatusRequestPromise;

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: "Menu" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Save CozSweet" })).toBeVisible();
 });

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

@@ -3,7 +3,7 @@ import { expect, test } from "@playwright/test";
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
 import {
   clearBrowserState,
-  defaultCharacterSidebarPath,
+  defaultCharacterProfilePath,
   defaultCharacterSplashPath,
   defaultCharacterChatUrl,
   enterChatFromSplash,
@@ -17,7 +17,7 @@ test.beforeEach(async ({ baseURL, context, page }) => {
   await mockCoreApis(page);
 });
 
-test("user can log out from the sidebar after email login", async ({
+test("user can log out from the profile after email login", async ({
   page,
 }) => {
   await enterChatFromSplash(page);
@@ -27,11 +27,14 @@ test("user can log out from the sidebar after email login", async ({
   await expect(page).toHaveURL(/\/auth(?:\?.*)?$/);
   await switchToEmailSignIn(page);
   await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
-  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+  await page.getByRole("link", { name: "Back to home" }).click();
+  await expect(page).toHaveURL(
+    new RegExp(defaultCharacterSplashPath.replace("?", "\\?") + "$"),
+  );
 
   await page.getByRole("button", { name: "Menu" }).click();
   await expect(page).toHaveURL(
-    new RegExp(defaultCharacterSidebarPath.replace("?", "\\?") + "$"),
+    new RegExp(defaultCharacterProfilePath.replace("?", "\\?") + "$"),
   );
 
   const logoutRequestPromise = page.waitForRequest("**/api/auth/logout");

e2e/specs/mock/auth/psid-login-from-external-entry.spec.ts

@@ -1,49 +1,74 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import {
-  clearBrowserState,
-  defaultCharacterChatUrl,
-} from "@e2e/fixtures/test-helpers";
+import { clearBrowserState } from "@e2e/fixtures/test-helpers";
 
-const psid = "e2e-facebook-psid";
+const handoffToken = "e2e-handoff-token-that-is-at-least-32-characters";
 
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
-  await mockCoreApis(page, { psidLoginFlow: true });
+  await mockCoreApis(page, { topUpHandoffFlow: true });
 });
 
-test("user enters from an external PSID link and becomes a guest", async ({
+test("user consumes a top-up handoff and opens credit packages as a formal Messenger user", async ({
   page,
 }) => {
-  const psidLoginRequestPromise = page.waitForRequest(
-    "**/api/auth/login/facebook/psid",
+  const handoffRequestPromise = page.waitForRequest(
+    "**/api/auth/handoff/topup/consume",
   );
 
-  await page.goto(`/external-entry?target=chat&psid=${psid}`);
+  await page.goto(
+    `/external-entry?target=topup&handoffToken=${encodeURIComponent(handoffToken)}`,
+  );
 
-  const psidLoginRequest = await psidLoginRequestPromise;
-  expect(psidLoginRequest.method()).toBe("POST");
-  expect(psidLoginRequest.postDataJSON()).toMatchObject({
-    psid,
-    bindToGuest: true,
-  });
-  expect(psidLoginRequest.postDataJSON().deviceId).toEqual(expect.any(String));
+  const handoffRequest = await handoffRequestPromise;
+  expect(handoffRequest.method()).toBe("POST");
+  expect(handoffRequest.postDataJSON()).toEqual({ handoffToken });
 
-  await expect(page).toHaveURL(defaultCharacterChatUrl);
-  await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+  await expect(page).toHaveURL("/subscription?type=topup");
+  await expect(
+    page.getByRole("button", { name: /Pay and Top Up/i }),
+  ).toBeVisible();
 
   await expect
     .poll(() =>
       page.evaluate(() => ({
         loginProvider: localStorage.getItem("cozsweet:login_provider"),
-        guestToken: localStorage.getItem("cozsweet:guest_token"),
-        psid: localStorage.getItem("cozsweet:psid"),
+        loginToken: localStorage.getItem("cozsweet:login_token"),
+        refreshToken: localStorage.getItem("cozsweet:refresh_token"),
       })),
     )
     .toMatchObject({
-      loginProvider: "guest",
-      guestToken: "e2e-psid-guest-token",
-      psid,
+      loginProvider: "facebookMessenger",
+      loginToken: "e2e-messenger-token",
+      refreshToken: "e2e-messenger-refresh-token",
     });
 });
+
+test("invalid top-up handoff does not log in and is removed from the URL", async ({
+  page,
+}) => {
+  await page.route("**/api/auth/handoff/topup/consume", async (route) => {
+    await route.fulfill({
+      status: 410,
+      json: {
+        detail: {
+          code: "HANDOFF_EXPIRED",
+          message: "充值链接已过期",
+        },
+      },
+    });
+  });
+
+  await page.goto(
+    `/external-entry?target=topup&handoffToken=${encodeURIComponent(handoffToken)}`,
+  );
+
+  await expect(page).toHaveURL("/external-entry?target=topup");
+  await expect(
+    page.getByText(/invalid or has expired/i),
+  ).toBeVisible();
+  await expect
+    .poll(() => page.evaluate(() => localStorage.getItem("cozsweet:login_provider")))
+    .not.toBe("facebookMessenger");
+});

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

@@ -0,0 +1,86 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import {
+  clearBrowserState,
+  defaultCharacterProfilePath,
+  dismissChatInterruptions,
+  enterChatFromSplash,
+  submitEmailLogin,
+  switchToEmailSignIn,
+} from "@e2e/fixtures/test-helpers";
+
+const characters = [
+  { slug: "elio", displayName: "Elio Silvestri" },
+  { slug: "maya", displayName: "Maya Tan" },
+  { slug: "nayeli", displayName: "Nayeli Cervantes" },
+] as const;
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("guest user avatar returns to Profile after sign-in", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page, { timeout: 30_000 });
+  await sendMessage(page, "Open my profile");
+
+  await page.getByRole("button", { name: "Open profile" }).click();
+
+  await expect(page).toHaveURL(/\/auth\?redirect=/);
+  expect(new URL(page.url()).searchParams.get("redirect")).toBe(
+    defaultCharacterProfilePath,
+  );
+  await switchToEmailSignIn(page);
+  await submitEmailLogin(page, {
+    expectedUrl: new RegExp(
+      `${defaultCharacterProfilePath.replace("?", "\\?")}$`,
+    ),
+  });
+});
+
+for (const character of characters) {
+  test(`${character.displayName} avatar opens the matching Private Zone`, async ({
+    page,
+  }) => {
+    await enterCharacterChat(page, character.slug);
+    await sendMessage(page, `Hello ${character.displayName}`);
+
+    await page
+      .getByRole("button", {
+        name: `Open ${character.displayName}'s private zone`,
+      })
+      .last()
+      .click();
+
+    await expect(page).toHaveURL(
+      new RegExp(`/characters/${character.slug}/private-zone(?:\\?.*)?$`),
+    );
+  });
+}
+
+async function enterCharacterChat(page: Page, characterSlug: string) {
+  const chatPath = `/characters/${characterSlug}/chat`;
+
+  await page.goto(`/characters/${characterSlug}/splash`);
+  await page.getByRole("button", { name: "Start Chatting" }).click();
+  await expect(page).toHaveURL(new RegExp(`${chatPath}(?:\\?.*)?$`));
+  await dismissChatInterruptions(page);
+  await expect(page.getByRole("textbox", { name: "Message" })).toBeEnabled({
+    timeout: 20_000,
+  });
+}
+
+async function sendMessage(page: Page, message: string) {
+  await dismissChatInterruptions(page);
+  const messageInput = page.getByRole("textbox", { name: "Message" });
+
+  await expect(messageInput).toBeEnabled({ timeout: 20_000 });
+  await messageInput.fill(message);
+  await messageInput.press("Enter");
+  await expect(page.getByRole("button", { name: "Open profile" })).toBeVisible({
+    timeout: 10_000,
+  });
+}

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

@@ -0,0 +1,49 @@
+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$/);
+});
+
+test("asks for consent before opening a user-bound discount plan", async ({
+  page,
+}) => {
+  await enterChatFromSplash(page);
+
+  const input = page.getByRole("textbox", { name: "Message" });
+  await input.fill("discount offer test");
+  await input.press("Enter");
+
+  const offer = page.getByLabel("Yes, ask for me");
+  await expect(offer).toContainText("Want me to ask for my best private offer?");
+  await offer.getByRole("button", { name: "Yes, ask for me" }).click();
+
+  await expect(page).toHaveURL(
+    /\/subscription\?type=vip.*planId=vip_annual.*commercialOfferId=13ec8a10/,
+  );
+});

e2e/specs/mock/chat/paid-image-promotion-topup.spec.ts

@@ -7,7 +7,6 @@ import {
   defaultCharacterChatUrl,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
-  setEmailSessionStorage,
   submitEmailLogin,
   switchToEmailSignIn,
 } from "@e2e/fixtures/test-helpers";
@@ -27,7 +26,10 @@ test("guest unlocks a promoted image through email login and top-up", async ({
   );
   await expect(page).toHaveURL(defaultCharacterChatUrl);
 
-  const unlockButton = page.getByRole("button", {
+  const promotedImageCard = page
+    .getByRole("group", { name: "Locked private image" })
+    .last();
+  const unlockButton = promotedImageCard.getByRole("button", {
     name: "Unlock private image",
   });
   await expect(unlockButton).toBeVisible({ timeout: 10_000 });
@@ -36,13 +38,10 @@ test("guest unlocks a promoted image through email login and top-up", async ({
   await expect(page).toHaveURL(/\/auth\?redirect=/);
 
   await switchToEmailSignIn(page);
-  await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
-
-  await setEmailSessionStorage(page);
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await page.reload();
+  await submitEmailLogin(page, { expectedUrl: defaultCharacterChatUrl });
 
   const unlockRequest = await unlockRequestPromise;
   expect(unlockRequest.method()).toBe("POST");

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,264 @@
+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 momentsRequest = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return (
+        url.pathname === "/api/private-zone/posts" &&
+        url.searchParams.get("characterId") === character.id
+      );
+    });
+    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 Promise.all([momentsRequest, albumRequest]);
+    await expect(
+      page.getByRole("heading", { name: "Private albums" }),
+    ).toBeVisible();
+    await expect(page.getByRole("tab")).toHaveText(["Albums", "Moments"]);
+    await expect(page.getByRole("tab", { name: "Albums" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    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/posts**", async (route) => {
+    const url = new URL(route.request().url());
+    const characterId = url.searchParams.get("characterId") ?? "elio";
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId,
+        items: [],
+        nextCursor: null,
+        hasMore: false,
+        creditBalance: 1000,
+        currency: "credits",
+      }),
+    });
+  });
+
+  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,7 +1,12 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import { paidImageMessageId } from "@e2e/fixtures/test-data";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import { createPaidImageHistoryResponse } from "@e2e/fixtures/data/chat";
+import {
+  paidImageDisplayMessageId,
+  paidImageMessageId,
+} from "@e2e/fixtures/test-data";
 import {
   clearBrowserState,
   completeVipPayment,
@@ -10,15 +15,10 @@ import {
   enterChatFromSplash,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
-  setEmailSessionStorage,
   submitEmailLogin,
   switchToEmailSignIn,
 } from "@e2e/fixtures/test-helpers";
 
-const paidImageOverlayUrl = new RegExp(
-  `${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
-);
-
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
   await mockCoreApis(page, {
@@ -44,38 +44,27 @@ test("guest can unlock a paid image after email login and subscription payment",
     message: "给我发图片",
   });
 
-  const paidImageButton = page.getByRole("button", {
-    name: "Open image in fullscreen",
+  const lockedImageCard = page.getByRole("group", {
+    name: "Locked private image",
   }).last();
-  await expect(paidImageButton).toBeVisible();
-
-  await paidImageButton.click();
-  await expect(page).toHaveURL(paidImageOverlayUrl);
-
-  const lockedImageDialog = page.getByRole("dialog", {
-    name: "Locked fullscreen image",
-  });
-  await expect(lockedImageDialog).toBeVisible();
-
-  await lockedImageDialog
-    .getByRole("button", { name: "Unlock high-definition large image" })
+  await expect(lockedImageCard).toBeVisible();
+  await expect(lockedImageCard.locator("img")).toHaveCount(0);
+  await lockedImageCard
+    .getByRole("button", { name: "Unlock private image" })
     .click();
 
   await expect(page).toHaveURL(/\/auth\?redirect=/);
   expect(new URL(page.url()).searchParams.get("redirect")).toBe(
-    `${defaultCharacterChatPath}?image=${paidImageMessageId}`,
+    defaultCharacterChatPath,
   );
 
   await switchToEmailSignIn(page);
-  await submitEmailLogin(page, {
-    expectedUrl: paidImageOverlayUrl,
-  });
-
-  await setEmailSessionStorage(page);
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await page.goto(`${defaultCharacterChatPath}?image=${paidImageMessageId}`);
+  await submitEmailLogin(page, {
+    expectedUrl: new RegExp(`${defaultCharacterChatPath}$`),
+  });
 
   const unlockRequest = await unlockRequestPromise;
   expect(unlockRequest.postDataJSON()).toMatchObject({
@@ -92,9 +81,44 @@ test("guest can unlock a paid image after email login and subscription payment",
 
   await expect(page).toHaveURL(
     new RegExp(
-      `${defaultCharacterChatPath}(?:\\?image=msg_photo_paywall_001)?$`,
+      `${defaultCharacterChatPath}(?:\\?image=${encodeURIComponent(paidImageDisplayMessageId)})?$`,
     ),
   );
   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);
+});

e2e/specs/mock/payment-dialog-layout.spec.ts

@@ -0,0 +1,119 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { stripePaymentDialogStyles } from "@/app/_components/payment/stripe-payment-dialog.styles";
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+
+const viewports = [
+  { width: 390, height: 844 },
+  { width: 405, height: 797 },
+  { width: 540, height: 900 },
+] as const;
+
+test.beforeEach(async ({ page }) => {
+  await mockCoreApis(page);
+});
+
+for (const viewport of viewports) {
+  test(`payment portal stays viewport-bound at ${viewport.width}x${viewport.height}`, async ({
+    page,
+  }) => {
+    await page.setViewportSize(viewport);
+    await page.goto("/subscription?type=topup", {
+      waitUntil: "domcontentloaded",
+    });
+
+    await mountPaymentPanel(page, 180);
+    await expectViewportScrim(page, viewport);
+    await expectCenteredShortPanel(page, viewport);
+
+    await mountPaymentPanel(page, 1_200);
+    await expectViewportScrim(page, viewport);
+    await expectScrollableTallPanel(page, viewport);
+  });
+}
+
+async function mountPaymentPanel(page: Page, contentHeight: number) {
+  await page.evaluate(
+    ({ dialogClassName, overlayClassName, requestedContentHeight }) => {
+      document.querySelector('[data-testid="payment-layout-overlay"]')?.remove();
+      document.querySelector('[data-testid="transformed-checkout-host"]')?.remove();
+
+      const transformedCheckoutHost = document.createElement("div");
+      transformedCheckoutHost.dataset.testid = "transformed-checkout-host";
+      transformedCheckoutHost.style.transform = "translateX(50%)";
+      document.body.appendChild(transformedCheckoutHost);
+
+      const overlay = document.createElement("div");
+      overlay.dataset.testid = "payment-layout-overlay";
+      overlay.className = overlayClassName;
+
+      const panel = document.createElement("div");
+      panel.dataset.testid = "payment-layout-panel";
+      panel.className = dialogClassName;
+
+      const content = document.createElement("div");
+      content.style.height = `${requestedContentHeight}px`;
+      content.textContent = "Complete payment";
+      panel.appendChild(content);
+      overlay.appendChild(panel);
+
+      // Mirrors ModalPortal: the overlay must be a body child, never a child of
+      // the transformed checkout host that triggered it.
+      document.body.appendChild(overlay);
+    },
+    {
+      dialogClassName: stripePaymentDialogStyles.dialog,
+      overlayClassName: stripePaymentDialogStyles.overlay,
+      requestedContentHeight: contentHeight,
+    },
+  );
+}
+
+async function expectViewportScrim(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const overlay = page.getByTestId("payment-layout-overlay");
+  await expect(overlay).toBeVisible();
+  const box = await overlay.boundingBox();
+
+  expect(box).not.toBeNull();
+  expect(box?.x).toBeCloseTo(0, 0);
+  expect(box?.y).toBeCloseTo(0, 0);
+  expect(box?.width).toBeCloseTo(viewport.width, 0);
+  expect(box?.height).toBeCloseTo(viewport.height, 0);
+  await expect(overlay.evaluate((node) => node.parentElement === document.body))
+    .resolves.toBe(true);
+}
+
+async function expectCenteredShortPanel(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const panel = page.getByTestId("payment-layout-panel");
+  const box = await panel.boundingBox();
+
+  expect(box).not.toBeNull();
+  expect(box?.y ?? 0).toBeGreaterThan(100);
+  expect(Math.abs((box?.y ?? 0) * 2 + (box?.height ?? 0) - viewport.height))
+    .toBeLessThanOrEqual(2);
+}
+
+async function expectScrollableTallPanel(
+  page: Page,
+  viewport: { width: number; height: number },
+) {
+  const panel = page.getByTestId("payment-layout-panel");
+  const box = await panel.boundingBox();
+  const scrollMetrics = await panel.evaluate((node) => ({
+    clientHeight: node.clientHeight,
+    scrollHeight: node.scrollHeight,
+  }));
+
+  expect(box).not.toBeNull();
+  expect(box?.y ?? 0).toBeGreaterThanOrEqual(15);
+  expect(box?.y ?? 100).toBeLessThanOrEqual(25);
+  expect((box?.y ?? 0) + (box?.height ?? 0))
+    .toBeLessThanOrEqual(viewport.height - 15);
+  expect(scrollMetrics.scrollHeight).toBeGreaterThan(scrollMetrics.clientHeight);
+}

e2e/specs/mock/payment/checkout-handoff-external-browser.spec.ts

@@ -0,0 +1,105 @@
+import { expect, test } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const facebookAndroidUserAgent =
+  "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Version/4.0 Chrome/126.0.0.0 Mobile Safari/537.36 " +
+  "[FB_IAB/FB4A;FBAV/566.0.0.48.73;]";
+const handoffToken = "checkout-handoff-token-that-is-at-least-32-characters";
+
+test.use({
+  userAgent: facebookAndroidUserAgent,
+  viewport: { width: 390, height: 844 },
+});
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+});
+
+test("consumes the handoff, removes its token, and does not create an order", async ({
+  page,
+}) => {
+  await mockCoreApis(page, { checkoutHandoffFlow: true });
+  let createOrderRequests = 0;
+  page.on("request", (request) => {
+    if (request.url().includes("/api/payment/create-order")) {
+      createOrderRequests += 1;
+    }
+  });
+  const consumeRequest = page.waitForRequest(
+    "**/api/auth/handoff/checkout/consume",
+  );
+
+  await page.goto(
+    `/external-entry?target=checkout&character=nayeli&handoffToken=${encodeURIComponent(handoffToken)}`,
+  );
+
+  expect((await consumeRequest).postDataJSON()).toEqual({ handoffToken });
+  await expect(page).toHaveURL(
+    /\/subscription\?planId=vip_monthly&autoRenew=1&character=nayeli&commercialOfferId=.*&payChannel=stripe/,
+  );
+  expect(page.url()).not.toContain("handoffToken");
+  await expect.poll(() => createOrderRequests).toBe(0);
+  await expect
+    .poll(() =>
+      page.evaluate(() => ({
+        loginProvider: localStorage.getItem("cozsweet:login_provider"),
+        loginToken: localStorage.getItem("cozsweet:login_token"),
+      })),
+    )
+    .toEqual({ loginProvider: "email", loginToken: "e2e-checkout-token" });
+});
+
+test("offers the Facebook external-browser path before creating a Stripe order", async ({
+  page,
+}) => {
+  await mockCoreApis(page);
+  let createOrderRequests = 0;
+  page.on("request", (request) => {
+    if (request.url().includes("/api/payment/create-order")) {
+      createOrderRequests += 1;
+    }
+  });
+  await page.route("**/api/auth/handoff/checkout", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        externalUrl:
+          "https://cozsweet.com/external-entry?target=checkout&handoffToken=opaque-token",
+        expiresAt: "2026-07-28T16:00:00+00:00",
+      }),
+    });
+  });
+
+  await seedEmailSession(page);
+  await page.goto("/subscription?type=vip&payChannel=stripe&character=maya");
+  await page.getByRole("button", { name: /Monthly,/i }).click();
+  const externalButton = page.getByRole("button", {
+    name: "Open in browser for more payment methods",
+  });
+  const paymentButton = page.getByRole("button", { name: "Pay and Top Up" });
+  await expect(externalButton).toBeVisible();
+  await expect(externalButton).toBeEnabled();
+  await expect(paymentButton).toBeVisible();
+  await expect(
+    page.getByRole("dialog", { name: "Automatic Renewal Confirmation" }),
+  ).toHaveCount(0);
+  const externalBox = await externalButton.boundingBox();
+  const paymentBox = await paymentButton.boundingBox();
+  expect(externalBox).not.toBeNull();
+  expect(paymentBox).not.toBeNull();
+  expect(externalBox!.y).toBeLessThan(paymentBox!.y);
+  expect(paymentBox!.y + paymentBox!.height).toBeLessThanOrEqual(844);
+  const handoffRequest = page.waitForRequest("**/api/auth/handoff/checkout");
+  await externalButton.click();
+  expect((await handoffRequest).postDataJSON()).toMatchObject({
+    planId: "vip_monthly",
+    autoRenew: true,
+  });
+  expect(createOrderRequests).toBe(0);
+});

e2e/specs/mock/payment/indonesia-qris.spec.ts

@@ -0,0 +1,364 @@
+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/user";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const idrPlans = {
+  plans: [
+    {
+      planId: "vip_monthly",
+      planName: "Monthly",
+      orderType: "vip_monthly",
+      amountCents: 19_590_000,
+      originalAmountCents: 19_590_000,
+      dailyPriceCents: 653_000,
+      currency: "IDR",
+      vipDays: 30,
+      dolAmount: null,
+      creditBalance: 3_000,
+    },
+    {
+      planId: "dol_1000",
+      planName: "1,000 Credits",
+      orderType: "dol",
+      amountCents: 8_890_000,
+      originalAmountCents: null,
+      dailyPriceCents: null,
+      currency: "IDR",
+      vipDays: null,
+      dolAmount: 1_000,
+      creditBalance: 1_000,
+    },
+  ],
+};
+
+const idrGiftCatalog = {
+  characterId: "elio",
+  categories: [
+    {
+      category: "coffee",
+      name: "Coffee",
+      productCount: 1,
+      imageUrl: null,
+    },
+  ],
+  plans: [
+    {
+      planId: "tip_coffee_usd_4_99",
+      planName: "Velvet Espresso",
+      orderType: "tip",
+      tipType: "coffee_small",
+      category: "coffee",
+      characterId: "elio",
+      description: "Buy Elio a Velvet Espresso",
+      imageUrl: null,
+      amountCents: 8_929_900,
+      currency: "IDR",
+      autoRenew: false,
+      isFirstRechargeOffer: false,
+      firstRechargeDiscountPercent: 0,
+      promotionType: null,
+    },
+  ],
+};
+
+async function registerIndonesiaPaymentMocks(page: Page) {
+  const orderStatuses = new Map<string, "pending" | "paid">();
+  const orderPlans = new Map<string, { planId: string; orderType: string }>();
+  let createOrderCount = 0;
+
+  await page.route("**/api/user/profile", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ ...e2eEmailUser, countryCode: "ID" }),
+    });
+  });
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(idrPlans) });
+  });
+  await page.route("**/api/payment/gift-products**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(idrGiftCatalog) });
+  });
+  await page.route("**/api/payment/create-order", async (route) => {
+    createOrderCount += 1;
+    const body = route.request().postDataJSON() as { planId: string };
+    const plan =
+      idrPlans.plans.find((item) => item.planId === body.planId) ??
+      idrGiftCatalog.plans.find((item) => item.planId === body.planId);
+    const orderId = `order_qris_${body.planId}`;
+    orderStatuses.set(orderId, "pending");
+    orderPlans.set(orderId, {
+      planId: body.planId,
+      orderType: plan?.orderType ?? "dol",
+    });
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId,
+        payParams: {
+          provider: "ezpay",
+          countryCode: "ID",
+          channelCode: "ID_QRIS_DYNAMIC_QR",
+          channelType: "QR",
+          payData: "00020101021226670016COM.NOBUBANK.WWW",
+          firstChargeAmountCents: plan?.amountCents ?? 0,
+          currency: "IDR",
+        },
+      }),
+    });
+  });
+  await page.route("**/api/payment/order-status**", async (route) => {
+    const url = new URL(route.request().url());
+    const orderId = url.searchParams.get("order_id") ?? "";
+    const plan = orderPlans.get(orderId);
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId,
+        status: orderStatuses.get(orderId) ?? "pending",
+        orderType: plan?.orderType ?? "dol",
+        planId: plan?.planId ?? null,
+        creditsAdded: 0,
+      }),
+    });
+  });
+  await page.route("**/api/payment/tip-message", async (route) => {
+    const body = route.request().postDataJSON() as { orderId: string };
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: body.orderId,
+        characterId: "elio",
+        planId: "tip_coffee_usd_4_99",
+        productName: "Velvet Espresso",
+        tipCount: 1,
+        poolIndex: 0,
+        message: "Thank you. Your gift made me smile.",
+      }),
+    });
+  });
+
+  return {
+    getCreateOrderCount() {
+      return createOrderCount;
+    },
+    markPaid(orderId: string) {
+      orderStatuses.set(orderId, "paid");
+    },
+  };
+}
+
+async function prepareIndonesiaUser(page: Page) {
+  await seedEmailSession(page);
+  await page.evaluate(() => {
+    const rawUser = localStorage.getItem("cozsweet:user");
+    const user = rawUser ? JSON.parse(rawUser) : {};
+    localStorage.setItem(
+      "cozsweet:user",
+      JSON.stringify({ ...user, countryCode: "ID" }),
+    );
+  });
+}
+
+async function expectQrisOrder(
+  page: Page,
+  buttonName: RegExp,
+  planId: string,
+  formattedAmount: RegExp,
+) {
+  const requestPromise = page.waitForRequest("**/api/payment/create-order");
+  await page.getByRole("button", { name: buttonName }).click();
+  const request = await requestPromise;
+  expect(request.postDataJSON()).toMatchObject({
+    planId,
+    payChannel: "ezpay",
+    recipientCharacterId: "elio",
+  });
+
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toContainText(formattedAmount);
+  await expect(dialog).toContainText("Waiting for payment");
+  await expect(
+    dialog.getByRole("img", { name: "QRIS payment QR code" }),
+  ).toBeVisible();
+  return `order_qris_${planId}`;
+}
+
+async function expectCheckoutButtonLayout(page: Page) {
+  const viewport = page.viewportSize();
+  const checkoutBox = await page
+    .getByRole("button", { name: "Pay and Top Up" })
+    .boundingBox();
+  const stripeBox = await page.getByRole("button", { name: "Stripe" }).boundingBox();
+  expect(viewport).not.toBeNull();
+  expect(checkoutBox).not.toBeNull();
+  expect(stripeBox).not.toBeNull();
+  if (!viewport || !checkoutBox || !stripeBox) return;
+  expect(checkoutBox.y + checkoutBox.height).toBeLessThanOrEqual(viewport.height);
+  expect(stripeBox.y + stripeBox.height).toBeLessThanOrEqual(checkoutBox.y);
+}
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("Indonesia VIP defaults to QRIS and completes after status polling", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=vip&character=elio");
+
+  await expect(page.getByText("Choose who you want to support")).toHaveCount(0);
+  await expect(page.getByText("Supporting Elio")).toHaveCount(0);
+  await expect(
+    page.getByRole("button", { name: "Elio", exact: true }),
+  ).toHaveCount(0);
+
+  await expect(page.getByRole("button", { name: "QRIS" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  const checkoutButton = page.getByRole("button", { name: "Pay and Top Up" });
+  await expect(checkoutButton).toBeEnabled();
+  await expectCheckoutButtonLayout(page);
+  await expect(
+    page.getByRole("dialog", { name: "Automatic Renewal Confirmation" }),
+  ).toHaveCount(0);
+  expect(payment.getCreateOrderCount()).toBe(0);
+
+  const orderId = await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "vip_monthly",
+    /Rp\s*195[.,]900/,
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+  payment.markPaid(orderId);
+
+  const success = page.getByRole("alertdialog", { name: "Payment successful" });
+  await expect(success).toBeVisible({ timeout: 10_000 });
+  await expect(
+    page.getByRole("dialog", { name: "Scan to pay with QRIS" }),
+  ).toBeHidden();
+});
+
+test("Indonesia credit top-up uses QRIS display cents", async ({ page }) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+  await expect(page.getByText("Supporting Elio")).toHaveCount(0);
+  await expectCheckoutButtonLayout(page);
+
+  const orderId = await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "dol_1000",
+    /Rp\s*88[.,]900/,
+  );
+  payment.markPaid(orderId);
+
+  await expect(
+    page.getByRole("alertdialog", { name: "Payment successful" }),
+  ).toBeVisible({ timeout: 10_000 });
+});
+
+test("closing QRIS restores payment selection and allows switching to Stripe", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await expectQrisOrder(
+    page,
+    /Pay and Top Up/i,
+    "dol_1000",
+    /Rp\s*88[.,]900/,
+  );
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await dialog.getByRole("button", { name: "Close" }).click();
+
+  await expect(dialog).toBeHidden();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  await expect(page.getByRole("button", { name: "Pay and Top Up" })).toBeEnabled();
+  expect(payment.getCreateOrderCount()).toBe(1);
+});
+
+test("payment issue submits Other to the feedback API without creating an order", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  let feedbackBody = "";
+  let idempotencyKey = "";
+  await page.route("**/api/feedback", async (route) => {
+    feedbackBody = route.request().postData() ?? "";
+    idempotencyKey = route.request().headers()["idempotency-key"] ?? "";
+    await route.fulfill({
+      json: apiEnvelope({ feedbackId: "feedback-payment-1", duplicate: false }),
+    });
+  });
+
+  await page.goto("/subscription?type=topup&character=elio");
+  await page.getByRole("button", { name: "Payment issue?" }).click();
+  const dialog = page.getByRole("dialog", {
+    name: "What problem did you encounter?",
+  });
+  await expect(dialog).toBeVisible();
+  await dialog.getByRole("radio", { name: "Other" }).check();
+  await dialog
+    .getByLabel("Please describe the issue")
+    .fill("QRIS did not open correctly.");
+  await dialog.getByRole("button", { name: "Submit" }).click();
+
+  await expect(page.getByRole("status")).toHaveText(
+    "Thanks. Your payment issue has been submitted.",
+  );
+  await expect(dialog).toBeHidden();
+  expect(payment.getCreateOrderCount()).toBe(0);
+  expect(idempotencyKey).toMatch(/^payment_feedback_[A-Za-z0-9_-]+$/);
+  expect(feedbackBody).toContain('name="category"');
+  expect(feedbackBody).toContain("payment");
+  expect(feedbackBody).toContain(
+    "Payment issue: Other\r\nDetails: QRIS did not open correctly.",
+  );
+  expect(feedbackBody).toContain('name="context"');
+  expect(feedbackBody).toContain('"paymentIssueReason":"other"');
+  expect(feedbackBody).toContain('"characterId":"elio"');
+});
+
+test("Indonesia gift checkout keeps IDR price through QRIS and thank-you flow", async ({
+  page,
+}) => {
+  const payment = await registerIndonesiaPaymentMocks(page);
+  await prepareIndonesiaUser(page);
+  await page.goto("/characters/elio/tip");
+
+  await expect(page.getByText(/IDR\s*89[.,]299/)).toBeVisible();
+  await expectQrisOrder(
+    page,
+    /Order and Buy/i,
+    "tip_coffee_usd_4_99",
+    /Rp\s*89[.,]299/,
+  );
+  const dialog = page.getByRole("dialog", { name: "Scan to pay with QRIS" });
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toBeHidden();
+
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+});

e2e/specs/mock/payment/legal-agreements.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "@playwright/test";
+
+test("serves the VIP membership benefits agreement from the same site", async ({
+  page,
+}) => {
+  const response = await page.goto("/legal/vip-membership-benefits.html");
+
+  expect(response?.status()).toBe(200);
+  await expect(
+    page.getByRole("heading", { name: "VIP Membership Benefits Agreement" }),
+  ).toBeVisible();
+});
+
+test("serves the automatic renewal agreement from the same site", async ({
+  page,
+}) => {
+  const response = await page.goto("/legal/automatic-renewal.html");
+
+  expect(response?.status()).toBe(200);
+  await expect(
+    page.getByRole("heading", { name: "Automatic Renewal Agreement" }),
+  ).toBeVisible();
+});

e2e/specs/mock/payment/philippines-gcash.spec.ts

@@ -0,0 +1,153 @@
+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/user";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const phpPlans = {
+  plans: [
+    {
+      planId: "dol_1000",
+      planName: "1,000 Credits",
+      orderType: "dol",
+      amountCents: 49_990,
+      originalAmountCents: 74_990,
+      dailyPriceCents: null,
+      currency: "PHP",
+      vipDays: null,
+      dolAmount: 1_000,
+      creditBalance: 1_000,
+    },
+  ],
+};
+
+async function registerPhilippinesPaymentMocks(
+  page: Page,
+  response: "hosted" | "qr",
+) {
+  let createOrderCount = 0;
+
+  await page.route("**/api/user/profile", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({ ...e2eEmailUser, countryCode: "PH" }),
+    });
+  });
+  await page.route("**/api/payment/plans**", async (route) => {
+    await route.fulfill({ json: apiEnvelope(phpPlans) });
+  });
+  await page.route("**/api/payment/create-order", async (route) => {
+    createOrderCount += 1;
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: `order_gcash_${response}`,
+        payParams: {
+          provider: "ezpay",
+          countryCode: "PH",
+          channelCode: "PH_QRPH_DYNAMIC",
+          channelType: "QR",
+          payData: "000201010212ph-qr-payload",
+          ...(response === "hosted"
+            ? { cashierUrl: "https://pay.example/gcash-hosted" }
+            : {}),
+          firstChargeAmountCents: 49_990,
+          currency: "PHP",
+        },
+      }),
+    });
+  });
+  await page.route("**/api/payment/order-status**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId: `order_gcash_${response}`,
+        status: "pending",
+        orderType: "dol",
+        planId: "dol_1000",
+        creditsAdded: 0,
+      }),
+    });
+  });
+
+  return {
+    getCreateOrderCount: () => createOrderCount,
+  };
+}
+
+async function preparePhilippinesUser(page: Page) {
+  await seedEmailSession(page);
+  await page.evaluate(() => {
+    const rawUser = localStorage.getItem("cozsweet:user");
+    const user = rawUser ? JSON.parse(rawUser) : {};
+    localStorage.setItem(
+      "cozsweet:user",
+      JSON.stringify({ ...user, countryCode: "PH" }),
+    );
+  });
+}
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+});
+
+test("Philippines checkout prefers the hosted GCash URL even for a QR response", async ({
+  page,
+}) => {
+  const payment = await registerPhilippinesPaymentMocks(page, "hosted");
+  await preparePhilippinesUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await expect(page.getByRole("button", { name: "GCash" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+
+  await expect(
+    page.getByRole("alertdialog", { name: "Continue to payment?" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("dialog", { name: "Pay with GCash / QR Ph" }),
+  ).toHaveCount(0);
+  await expect(
+    page.getByRole("dialog", { name: "Scan to pay with QRIS" }),
+  ).toHaveCount(0);
+  expect(payment.getCreateOrderCount()).toBe(1);
+
+  await page.getByRole("button", { name: "Cancel" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  expect(payment.getCreateOrderCount()).toBe(1);
+});
+
+test("Philippines QR-only fallback is labeled GCash / QR Ph and can switch to Stripe", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  const payment = await registerPhilippinesPaymentMocks(page, "qr");
+  await preparePhilippinesUser(page);
+  await page.goto("/subscription?type=topup&character=elio");
+
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+  const dialog = page.getByRole("dialog", {
+    name: "Pay with GCash / QR Ph",
+  });
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toContainText(/₱\s*499\.90/);
+  await expect(dialog).not.toContainText("QRIS");
+  await expect(
+    dialog.getByRole("img", { name: "GCash / QR Ph payment QR code" }),
+  ).toBeVisible();
+
+  await dialog.getByRole("button", { name: "Close" }).click();
+  await expect(dialog).toBeHidden();
+  await expect(page.getByRole("button", { name: "Stripe" })).toBeEnabled();
+  await page.getByRole("button", { name: "Stripe" }).click();
+  await expect(page.getByRole("button", { name: "Stripe" })).toHaveAttribute(
+    "aria-pressed",
+    "true",
+  );
+  expect(payment.getCreateOrderCount()).toBe(1);
+});

e2e/specs/mock/private-zone-video.spec.ts

@@ -0,0 +1,164 @@
+import { expect, test, type Page } from "@playwright/test";
+
+import { mockCoreApis } from "@e2e/fixtures/api-mocks";
+import { apiEnvelope } from "@e2e/fixtures/data/common";
+import {
+  clearBrowserState,
+  seedEmailSession,
+} from "@e2e/fixtures/test-helpers";
+
+const postId = "11111111-1111-1111-1111-111111111111";
+let unlocked = false;
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  unlocked = false;
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerPrivateZoneVideoMocks(page);
+});
+
+test("Private Zone defaults to Albums and reveals video after switching to Moments", async ({
+  page,
+}) => {
+  await seedEmailSession(page);
+
+  const listRequest = page.waitForRequest((request) => {
+    const url = new URL(request.url());
+    return (
+      url.pathname === "/api/private-zone/posts" &&
+      url.searchParams.get("characterId") === "maya-tan"
+    );
+  });
+  await page.goto("/characters/maya/private-zone");
+  await listRequest;
+
+  await expect(
+    page.getByRole("heading", { name: "Private albums" }),
+  ).toBeVisible();
+  await expect(page.getByText("Maya archive")).toBeVisible();
+  await page.getByRole("tab", { name: "Moments" }).click();
+  await expect(
+    page.getByRole("heading", { name: "Private moments" }),
+  ).toBeVisible();
+  await expect(page.getByText("Only for you.")).toBeVisible();
+  await expect(page.locator("video")).toHaveCount(0);
+
+  await page.getByRole("button", { name: "Unlock for 100 credits" }).click();
+  const dialog = page.getByRole("alertdialog");
+  await expect(dialog).toContainText("100 credits");
+  const unlockRequest = page.waitForRequest(
+    `**/api/private-zone/posts/${postId}/unlock`,
+  );
+  await dialog.getByRole("button", { name: "Unlock", exact: true }).click();
+  expect((await unlockRequest).postDataJSON()).toEqual({ expectedCost: 100 });
+
+  const video = page.locator("video");
+  await expect(video).toHaveCount(1);
+  await expect(video.locator("source")).toHaveAttribute("src", /video\.mp4/);
+  await expect(page.getByRole("alertdialog")).toHaveCount(0);
+});
+
+test("Albums render first and Moments remain available behind the second tab", async ({ page }) => {
+  await seedEmailSession(page);
+  await page.goto("/characters/maya/private-zone");
+
+  const tabs = page.getByRole("tab");
+  await expect(tabs).toHaveText(["Albums", "Moments"]);
+  await expect(page.getByRole("tab", { name: "Albums" })).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(
+    page.getByRole("heading", { name: "Private albums" }),
+  ).toBeVisible();
+  await expect(page.getByText("Maya archive")).toBeVisible();
+
+  await page.getByRole("tab", { name: "Moments" }).click();
+  await expect(page.getByRole("tab", { name: "Moments" })).toHaveAttribute(
+    "aria-selected",
+    "true",
+  );
+  await expect(
+    page.getByRole("heading", { name: "Private moments" }),
+  ).toBeVisible();
+});
+
+async function registerPrivateZoneVideoMocks(page: Page): Promise<void> {
+  await page.route("**/api/private-zone/posts**", async (route) => {
+    const url = new URL(route.request().url());
+    await route.fulfill({
+      json: apiEnvelope({
+        characterId: url.searchParams.get("characterId") ?? "maya-tan",
+        items: [videoPost(unlocked)],
+        nextCursor: null,
+        hasMore: false,
+        creditBalance: unlocked ? 150 : 250,
+        currency: "credits",
+      }),
+    });
+  });
+
+  // Playwright evaluates page routes in reverse registration order. Register
+  // the specific mutation last so the broader list route cannot intercept it.
+  await page.route("**/api/private-zone/posts/*/unlock", async (route) => {
+    unlocked = true;
+    await route.fulfill({
+      json: apiEnvelope({
+        postId,
+        reason: "ok",
+        unlocked: true,
+        creditsCharged: 100,
+        requiredCredits: 100,
+        currentCredits: 150,
+        shortfallCredits: 0,
+        creditBalance: 150,
+        post: videoPost(true),
+      }),
+    });
+  });
+
+  await page.route("**/api/private-zone/albums**", async (route) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        items: [
+          {
+            albumId: "album-maya",
+            title: "Maya archive",
+            content: null,
+            previewText: "Private photos",
+            imageCount: 1,
+            images: [{ url: "/images/private-zone/banner/maya.png", locked: true, index: 0 }],
+            locked: true,
+            unlocked: false,
+            unlockCost: 80,
+            publishedAt: "2026-07-24T10:00:00+00:00",
+            lockDetail: { locked: true },
+          },
+        ],
+        creditBalance: 250,
+        pendingImageCount: 0,
+        hasIncompleteContent: false,
+      }),
+    });
+  });
+}
+
+function videoPost(isUnlocked: boolean) {
+  return {
+    postId,
+    characterId: "maya-tan",
+    caption: "Only for you.",
+    posterUrl: "/images/private-zone/banner/maya.png",
+    mediaType: "video",
+    videoUrl: isUnlocked ? "/test-video.mp4?token=short" : null,
+    videoMimeType: "video/mp4",
+    videoSizeBytes: 1024,
+    durationSeconds: 18,
+    unlockCostCredits: 100,
+    currency: "credits",
+    locked: !isUnlocked,
+    unlocked: isUnlocked,
+    availableForNewUnlock: true,
+    publishedAt: "2026-07-24T10:00:00+00:00",
+  };
+}

e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts

@@ -1,20 +1,17 @@
 import { expect, test } from "@playwright/test";
 
 import { mockCoreApis } from "@e2e/fixtures/api-mocks";
-import { paidImageMessageId } from "@e2e/fixtures/test-data";
+import {
+  paidImageMessageId,
+} from "@e2e/fixtures/test-data";
 import {
   clearBrowserState,
-  defaultCharacterChatPath,
   dismissChatInterruptions,
   expectInsufficientCreditsDialog,
   expectVipChatSubscriptionUrl,
   signInWithEmailAndOpenChat,
 } from "@e2e/fixtures/test-helpers";
 
-const paidImageOverlayUrl = new RegExp(
-  `${defaultCharacterChatPath}\\?image=${paidImageMessageId}$`,
-);
-
 test.beforeEach(async ({ baseURL, context, page }) => {
   await clearBrowserState(context, page, baseURL);
   await mockCoreApis(page, {
@@ -22,30 +19,23 @@ test.beforeEach(async ({ baseURL, context, page }) => {
   });
 });
 
-test("user sees insufficient credits when unlocking a paid image from fullscreen and can navigate to subscription", async ({
+test("user sees insufficient credits when unlocking from the locked image card and can navigate to subscription", async ({
   page,
 }) => {
   await signInWithEmailAndOpenChat(page);
   await dismissChatInterruptions(page);
 
-  const paidImageButton = page.getByRole("button", {
-    name: "Open image in fullscreen",
+  const lockedImageCard = page.getByRole("group", {
+    name: "Locked private image",
   }).last();
-  await expect(paidImageButton).toBeVisible({ timeout: 10_000 });
-
-  await paidImageButton.click();
-  await expect(page).toHaveURL(paidImageOverlayUrl);
-
-  const lockedImageDialog = page.getByRole("dialog", {
-    name: "Locked fullscreen image",
-  });
-  await expect(lockedImageDialog).toBeVisible();
+  await expect(lockedImageCard).toBeVisible({ timeout: 10_000 });
+  await expect(lockedImageCard.locator("img")).toHaveCount(0);
 
   const unlockRequestPromise = page.waitForRequest(
     "**/api/chat/unlock-private",
   );
-  await lockedImageDialog
-    .getByRole("button", { name: "Unlock high-definition large image" })
+  await lockedImageCard
+    .getByRole("button", { name: "Unlock private image" })
     .click();
 
   const unlockRequest = await unlockRequestPromise;

e2e/specs/real/email-login-from-other-options.spec.ts

@@ -42,7 +42,7 @@ test.describe("pre-release email login smoke", () => {
       urlTimeout: 20_000,
     });
 
-    await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+    await expect(page.getByRole("button", { name: "Profile" })).toBeVisible();
     await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
   });
 });

env-example/.env.local.example

@@ -5,6 +5,7 @@ NEXTAUTH_URL=https://frontend-test.banlv-ai.com
 NEXTAUTH_URL_INTERNAL=http://localhost:3000
 NEXT_PUBLIC_API_BASE_URL=https://proapi.banlv-ai.com
 NEXT_PUBLIC_WS_BASE_URL=wss://proapi.banlv-ai.com/ws
+NEXT_PUBLIC_ENABLE_VOICE_CALL=false
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51Te8ybEJDtUGxQHo0UMySJ2hW0vVryynzllmIUI3UQdQCFgxNLci0Jmm2lQkRsTaIP7C7IQlFzfFyBJ5rOhr1ML800G8P8DF5R
 
 NEXT_PUBLIC_API_CONNECT_TIMEOUT=30000

env-example/.env.production.example

@@ -10,6 +10,7 @@ NEXT_PUBLIC_API_BASE_URL=https://api.banlv-ai.com
 
 # WebSocket URL（生产环境）
 NEXT_PUBLIC_WS_BASE_URL=wss://api.banlv-ai.com/ws
+NEXT_PUBLIC_ENABLE_VOICE_CALL=false
 
 # Stripe 支付（publishable key 可暴露在浏览器端）
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51Te8ybEJDtUGxQHouKlEMfMuCZWifzlhBIReeKvANOtyCXS4zL0SMTWJXiFHPKz7azpF6OnIKXUPFSLs82fevVjr00w1bw5mvl

package.json

@@ -25,9 +25,9 @@
     "test:e2e:chrome": "PLAYWRIGHT_USE_SYSTEM_CHROME=1 playwright test --project=mock-chromium",
     "test:e2e:headed": "playwright test --project=mock-chromium --headed",
     "test:e2e:ui": "playwright test --ui",
-    "test:e2e:mobile-smoke": "playwright test --project=mock-mobile-chrome e2e/specs/mock/auth/email-login-from-other-options.spec.ts e2e/specs/mock/auth/logout-from-sidebar.spec.ts e2e/specs/mock/chat/chat-send-token-refresh-retry.spec.ts e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts",
+    "test:e2e:mobile-smoke": "playwright test --project=mock-mobile-chrome e2e/specs/mock/auth/email-login-from-other-options.spec.ts e2e/specs/mock/auth/logout-from-profile.spec.ts e2e/specs/mock/chat/chat-send-token-refresh-retry.spec.ts e2e/specs/mock/unlock-message/image-unlock-insufficient-credits.spec.ts",
     "test:e2e:real": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://frontend-test.banlv-ai.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://proapi.banlv-ai.com} playwright test --project=real-backend",
-    "test:e2e:prod": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://cozsweet.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://proapi.banlv-ai.com} playwright test --project=prod-smoke",
+    "test:e2e:prod": "E2E_REAL_BACKEND=1 PLAYWRIGHT_BASE_URL=${PLAYWRIGHT_BASE_URL:-https://cozsweet.com} E2E_API_BASE_URL=${E2E_API_BASE_URL:-https://api.banlv-ai.com} playwright test --project=prod-smoke",
     "contract:check": "node scripts/contracts/check-openapi.mjs",
     "test:contracts": "node --test scripts/contracts/__tests__/*.test.mjs",
     "perf:bundle": "next experimental-analyze --output && node scripts/performance/report-bundle.mjs",
@@ -50,6 +50,7 @@
     "next-auth": "^4.24.14",
     "ofetch": "^1.5.1",
     "pino": "^10.3.1",
+    "qrcode.react": "^4.2.0",
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "react-icons": "^5.6.0",

playwright.config.ts

@@ -12,7 +12,10 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: Boolean(process.env.CI),
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
+  // Next.js dev + Turbopack can return incomplete module payloads when the
+  // local mock suite compiles many routes concurrently. Keep this tier
+  // deterministic locally as well as in CI.
+  workers: 1,
   reporter: process.env.CI
     ? [["list"], ["html", { open: "never" }]]
     : [["list"], ["html", { open: "never" }]],

pnpm-lock.yaml

@@ -50,6 +50,9 @@ importers:
       pino:
         specifier: ^10.3.1
         version: 10.3.1
+      qrcode.react:
+        specifier: ^4.2.0
+        version: 4.2.0(react@19.2.4)
       react:
         specifier: 19.2.4
         version: 19.2.4
@@ -3290,6 +3293,11 @@ packages:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
 
+  qrcode.react@4.2.0:
+    resolution: {integrity: sha512-QpgqWi8rD9DsS9EP3z7BT+5lY5SFhsqGjpgW5DY/i3mK4M9DTBNz3ErMi8BWYEfI3L0d8GIbGmcdFAS1uIRGjA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   queue-microtask@1.2.3:
     resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
 
@@ -7085,6 +7093,10 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qrcode.react@4.2.0(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+
   queue-microtask@1.2.3: {}
 
   quick-format-unescaped@4.0.4: {}

public/legal/automatic-renewal.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light" />
+    <title>Automatic Renewal Agreement | Cozsweet</title>
+    <style>
+      :root { font-family: Georgia, "Times New Roman", serif; color: #2b1721; background: #fff8fb; }
+      * { box-sizing: border-box; }
+      body { margin: 0; padding: 24px 16px 48px; line-height: 1.65; }
+      main { width: min(100%, 760px); margin: 0 auto; padding: clamp(22px, 6vw, 48px); border: 1px solid #f3c6dc; border-radius: 24px; background: #fff; box-shadow: 0 18px 50px rgba(133, 45, 88, .1); }
+      h1 { margin: 0 0 8px; font-size: clamp(28px, 7vw, 42px); line-height: 1.12; }
+      h2 { margin: 28px 0 8px; font-size: 21px; }
+      p, li { font-family: Arial, Helvetica, sans-serif; color: #553d49; }
+      .meta { margin: 0 0 28px; color: #8c6176; font-size: 14px; }
+      .notice { padding: 14px 16px; border-radius: 14px; background: #fff0f7; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Automatic Renewal Agreement</h1>
+      <p class="meta">Effective date: July 29, 2026</p>
+
+      <p class="notice">
+        By selecting <strong>Confirm</strong> before payment, you authorize Cozsweet and its payment provider to renew the selected membership automatically under the terms shown below.
+      </p>
+
+      <h2>1. When renewal applies</h2>
+      <p>
+        Automatic renewal applies only when the selected membership is identified as auto-renewing in the purchase flow. One-time credit purchases, tips, gifts, lifetime plans, and payment methods explicitly shown as one-time purchases do not automatically renew.
+      </p>
+
+      <h2>2. Billing frequency</h2>
+      <p>
+        The plan renews at the end of the billing period shown at checkout, such as monthly, quarterly, or annually. Renewal continues until cancelled. Your payment method may be charged shortly before or on the start of the next period as permitted by the payment provider.
+      </p>
+
+      <h2>3. Renewal amount</h2>
+      <p>
+        The initial charge and renewal amount are displayed before confirmation. A promotion may reduce the first charge without reducing later renewals. Unless another renewal amount is shown, renewal uses the applicable regular price for the selected plan, together with any taxes or fees required by law.
+      </p>
+
+      <h2>4. Confirmation</h2>
+      <p>
+        Cozsweet asks for renewal confirmation when an account first attempts to pay for an automatically renewing membership in the current agreement version. Cancelling the confirmation does not create an order. Confirming records the acknowledgement in the current browser and continues to payment.
+      </p>
+
+      <h2>5. Cancellation</h2>
+      <p>
+        You may cancel future renewal using a cancellation option made available in the product or by using the support/payment-issue path before the next renewal is processed. Cancellation takes effect for future billing; membership already paid for normally remains available until the end of the current term.
+      </p>
+
+      <h2>6. Failed or disputed payments</h2>
+      <p>
+        A failed renewal can interrupt membership benefits. If you see a duplicate charge, a long-pending payment, or missing benefits, do not repeatedly submit payment. Use <strong>Payment issue?</strong> on the purchase page and keep the returned Feedback ID. Never provide passwords, full card numbers, security codes, verification codes, or access tokens.
+      </p>
+
+      <h2>7. Material changes</h2>
+      <p>
+        If the renewal terms materially change, Cozsweet will update this agreement and request a new acknowledgement when required. The version effective for a payment is the version linked from its confirmation dialog.
+      </p>
+    </main>
+  </body>
+</html>

public/legal/vip-membership-benefits.html

@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light" />
+    <title>VIP Membership Benefits Agreement | Cozsweet</title>
+    <style>
+      :root { font-family: Georgia, "Times New Roman", serif; color: #2b1721; background: #fff8fb; }
+      * { box-sizing: border-box; }
+      body { margin: 0; padding: 24px 16px 48px; line-height: 1.65; }
+      main { width: min(100%, 760px); margin: 0 auto; padding: clamp(22px, 6vw, 48px); border: 1px solid #f3c6dc; border-radius: 24px; background: #fff; box-shadow: 0 18px 50px rgba(133, 45, 88, .1); }
+      h1 { margin: 0 0 8px; font-size: clamp(28px, 7vw, 42px); line-height: 1.12; }
+      h2 { margin: 28px 0 8px; font-size: 21px; }
+      p, li { font-family: Arial, Helvetica, sans-serif; color: #553d49; }
+      .meta { margin: 0 0 28px; color: #8c6176; font-size: 14px; }
+      a { color: #d8327c; }
+      .notice { padding: 14px 16px; border-radius: 14px; background: #fff0f7; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>VIP Membership Benefits Agreement</h1>
+      <p class="meta">Effective date: July 29, 2026</p>
+
+      <p class="notice">
+        This agreement explains the VIP membership displayed on the Cozsweet purchase page. The plan name, price, currency, duration, credits, and benefits shown at checkout are the terms that apply to your purchase.
+      </p>
+
+      <h2>1. Membership benefits</h2>
+      <p>
+        VIP may include the chat access, credits, private content access, or other benefits displayed for the selected plan. Benefits are available only for the membership period and account shown at checkout. A membership does not guarantee that every feature or item is free; some content can still require credits or a separate purchase when clearly shown in the product.
+      </p>
+
+      <h2>2. Plan term and account</h2>
+      <p>
+        Membership is attached to the Cozsweet account used for payment. The selected monthly, quarterly, annual, lifetime, or other plan term is shown before payment. Do not share payment credentials or account access with another person.
+      </p>
+
+      <h2>3. Automatic renewal</h2>
+      <p>
+        A plan marked as automatically renewing continues until cancelled. Before the first automatically renewing purchase, Cozsweet displays a separate confirmation. Please also read the <a href="/legal/automatic-renewal.html">Automatic Renewal Agreement</a>.
+      </p>
+
+      <h2>4. Prices and promotions</h2>
+      <p>
+        The checkout page is the source of truth for the current amount and currency. A first-payment or limited promotion can apply only to the initial charge; the renewal amount may be the regular price displayed in the renewal notice. Cozsweet does not ask you to pay a price that is not shown in the checkout flow.
+      </p>
+
+      <h2>5. Payment and access</h2>
+      <p>
+        Benefits are activated only after payment is confirmed and the order is fulfilled. A pending or failed payment does not activate membership. If payment is duplicated, remains pending, or benefits are missing, do not submit repeated payments; use the <strong>Payment issue?</strong> entry on the purchase page and retain the returned Feedback ID.
+      </p>
+
+      <h2>6. Cancellation, refunds, and applicable rights</h2>
+      <p>
+        Cancellation stops future renewal but does not normally remove benefits already paid for during the current term. Refund rights depend on applicable law, the payment provider, and the circumstances of the order. Use the product support or payment-issue path for review; never send a password, card number, security code, verification code, or access token.
+      </p>
+
+      <h2>7. Changes</h2>
+      <p>
+        If a material membership term changes, the updated version and effective date will be made available before it applies to a new purchase or renewal where required.
+      </p>
+    </main>
+  </body>
+</html>

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-room/albums/{albumId}/unlock",
+          path: "/api/private-zone/albums/{albumId}/unlock",
         },
       },
       {
         paths: {
           "/api/chat/history": { get: {} },
-          "/api/private-room/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 路径
-WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test"
-echo "=== 进入 test 分支 worktree ==="
+# pre 分支 worktree 路径
+WORKTREE_PATH="/Users/chase/Documents/frontend/cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre"
+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/）
-echo "=== 复制测试环境图标（icons/test → public/） ==="
+# 复制预发环境图标（运行资源目录仍为 icons/test）
+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）
-echo "=== 准备测试环境变量（env-example/.env.local.example → .env.local） ==="
+# 准备预发环境变量（运行配置仍使用 .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 "=== 预发布完成 ==="

scripts/server/deploy-docker-image.sh

@@ -49,8 +49,6 @@ echo "=== compose project: $COMPOSE_PROJECT_NAME ==="
 "${COMPOSE[@]}" up -d --remove-orphans --no-build web
 "${COMPOSE[@]}" ps
 
-docker image prune -f
-
 prune_project_images() {
   local retain_count="$1"
   if ! [[ "$retain_count" =~ ^[0-9]+$ ]] || [ "$retain_count" -le 0 ]; then

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

@@ -79,4 +79,34 @@ describe("shared Tailwind components", () => {
     expect(guestHtml).toContain('aria-label="Guest avatar"');
     expect(guestHtml).toContain("%2Fimages%2Favatar%2Fplaceholder.png");
   });
+
+  it("renders interactive avatars as accessible buttons", () => {
+    const characterHtml = renderToStaticMarkup(
+      <CharacterAvatar
+        src="/images/avatar/elio.png"
+        alt="Elio Silvestri"
+        actionLabel="Open Elio's private zone"
+        analyticsKey="chat.open_private_zone_from_avatar"
+        onClick={() => undefined}
+      />,
+    );
+    const userHtml = renderToStaticMarkup(
+      <UserMessageAvatar
+        actionLabel="Open profile"
+        analyticsKey="chat.open_profile_from_avatar"
+        onClick={() => undefined}
+      />,
+    );
+
+    expect(characterHtml).toContain('<button type="button"');
+    expect(characterHtml).toContain(
+      'aria-label="Open Elio&#x27;s private zone"',
+    );
+    expect(characterHtml).toContain(
+      'data-analytics-key="chat.open_private_zone_from_avatar"',
+    );
+    expect(userHtml).toContain('<button type="button"');
+    expect(userHtml).toContain('aria-label="Open profile"');
+    expect(userHtml).toContain("focus-visible:outline-3");
+  });
 });

src/app/_components/avatar-interaction.ts

@@ -0,0 +1,11 @@
+export type AvatarInteractionProps =
+  | {
+      onClick?: undefined;
+      actionLabel?: never;
+      analyticsKey?: never;
+    }
+  | {
+      onClick: () => void;
+      actionLabel: string;
+      analyticsKey?: string;
+    };

src/app/_components/character-avatar.tsx

@@ -3,7 +3,9 @@
 import Image from "next/image";
 import type { CSSProperties } from "react";
 
-export interface CharacterAvatarProps {
+import type { AvatarInteractionProps } from "./avatar-interaction";
+
+interface CharacterAvatarVisualProps {
   src: string;
   alt: string;
   className?: string;
@@ -12,6 +14,9 @@ export interface CharacterAvatarProps {
   priority?: boolean;
 }
 
+export type CharacterAvatarProps = CharacterAvatarVisualProps &
+  AvatarInteractionProps;
+
 export function CharacterAvatar({
   src,
   alt,
@@ -19,6 +24,9 @@ export function CharacterAvatar({
   size = 43,
   imageSize,
   priority = false,
+  onClick,
+  actionLabel,
+  analyticsKey,
 }: CharacterAvatarProps) {
   const resolvedImageSize =
     imageSize ?? (typeof size === "number" ? size : 96);
@@ -27,16 +35,16 @@ export function CharacterAvatar({
     height: size,
   };
 
-  return (
-    <span
-      className={[
-        "inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full bg-(--color-avatar-border,#fbf3f5)",
+  const avatarClassName = [
+    "inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full border-0 bg-(--color-avatar-border,#fbf3f5)",
+    onClick
+      ? "cursor-pointer p-0 transition-transform duration-150 focus-visible:outline-3 focus-visible:outline-offset-3 focus-visible:outline-accent active:scale-96"
+      : undefined,
     className,
   ]
     .filter(Boolean)
-        .join(" ")}
-      style={style}
-    >
+    .join(" ");
+  const image = (
     <Image
       src={src}
       alt={alt}
@@ -45,6 +53,27 @@ export function CharacterAvatar({
       priority={priority}
       className="size-full object-cover"
     />
+  );
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        className={avatarClassName}
+        style={style}
+        aria-label={actionLabel}
+        data-analytics-key={analyticsKey}
+        data-analytics-label={actionLabel}
+        onClick={onClick}
+      >
+        {image}
+      </button>
+    );
+  }
+
+  return (
+    <span className={avatarClassName} style={style}>
+      {image}
     </span>
   );
 }

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__/modal-portal.test.tsx

@@ -0,0 +1,119 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ModalPortal } from "../modal-portal";
+
+describe("ModalPortal", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    container.style.transform = "translateX(50%)";
+    document.body.appendChild(container);
+    document.body.style.overflow = "auto";
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
+  it("portals outside transformed ancestors and exposes dialog semantics", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <ModalPortal
+          open
+          onClose={onClose}
+          scrimClassName="fixed inset-0"
+          panelClassName="payment-panel"
+          scrimOpacity={0.5}
+          role="alertdialog"
+          ariaLabelledBy="payment-title"
+          ariaDescribedBy="payment-description"
+        >
+          <h2 id="payment-title">Complete payment</h2>
+          <p id="payment-description">Choose a payment method.</p>
+        </ModalPortal>,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.parentElement?.parentElement).toBe(document.body);
+    expect(dialog?.getAttribute("aria-labelledby")).toBe("payment-title");
+    expect(dialog?.getAttribute("aria-describedby")).toBe(
+      "payment-description",
+    );
+    expect(document.body.style.overflow).toBe("hidden");
+  });
+
+  it("restores the previous body overflow after the final modal closes", () => {
+    const renderModals = (showFirst: boolean, showSecond: boolean) => (
+      <>
+        <ModalPortal
+          open={showFirst}
+          onClose={() => undefined}
+          scrimClassName="first-scrim"
+          panelClassName="first-panel"
+          scrimOpacity={0.4}
+        >
+          First
+        </ModalPortal>
+        <ModalPortal
+          open={showSecond}
+          onClose={() => undefined}
+          scrimClassName="second-scrim"
+          panelClassName="second-panel"
+          scrimOpacity={0.4}
+        >
+          Second
+        </ModalPortal>
+      </>
+    );
+
+    act(() => root.render(renderModals(true, true)));
+    expect(document.body.style.overflow).toBe("hidden");
+
+    act(() => root.render(renderModals(false, true)));
+    expect(document.body.style.overflow).toBe("hidden");
+
+    act(() => root.render(renderModals(false, false)));
+    expect(document.body.style.overflow).toBe("auto");
+  });
+
+  it("keeps persistent payment modals open on scrim click and Escape", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <ModalPortal
+          open
+          persistent
+          onClose={onClose}
+          scrimClassName="fixed inset-0"
+          panelClassName="payment-panel"
+          scrimOpacity={0.5}
+        >
+          Payment
+        </ModalPortal>,
+      ),
+    );
+
+    const scrim = document.body.querySelector(".fixed.inset-0");
+    act(() => scrim?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    act(() =>
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })),
+    );
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});

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

@@ -79,18 +79,20 @@ describe("core Tailwind components", () => {
       <AppBottomNav
         activeItem="chat"
         variant="dark"
-        privateRoomLabel="Maya Private room"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateRoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
-    const privateRoomHtml = renderToStaticMarkup(
+    const privateZoneHtml = renderToStaticMarkup(
       <AppBottomNav
-        activeItem="privateRoom"
+        activeItem="privateZone"
         variant="warm"
-        privateRoomLabel="Maya Private room"
+        privateZoneLabel="Maya Private Zone"
         onChatClick={() => undefined}
-        onPrivateRoomClick={() => undefined}
+        onPrivateZoneClick={() => undefined}
+        onMenuClick={() => undefined}
       />,
     );
 
@@ -99,13 +101,15 @@ describe("core Tailwind components", () => {
     expect(chatHtml).toMatch(
       /<button[^>]*aria-current="page"[^>]*>.*?<span>Chat<\/span>/,
     );
-    expect(privateRoomHtml).toMatch(/class="[^"]*warm[^"]*"/);
-    expect(privateRoomHtml).toMatch(
-      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private room<\/span>/,
+    expect(privateZoneHtml).toMatch(/class="[^"]*warm[^"]*"/);
+    expect(privateZoneHtml).toMatch(
+      /<button[^>]*aria-current="page"[^>]*>.*?<span>Maya Private Zone<\/span>/,
     );
     expect(chatHtml).toContain('data-analytics-key="navigation.chat"');
-    expect(privateRoomHtml).toContain(
-      'data-analytics-key="navigation.private_room"',
+    expect(privateZoneHtml).toContain(
+      'data-analytics-key="navigation.private_zone"',
     );
+    expect(chatHtml).toContain('data-analytics-key="navigation.menu"');
+    expect(chatHtml).toContain("<span>Menu</span>");
   });
 });

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

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

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

@@ -1,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" | "privateRoom";
+export type AppBottomNavItem = "chat" | "privateZone" | "menu";
 export type AppBottomNavVariant = "warm" | "dark";
 
 export interface AppBottomNavProps {
   activeItem?: AppBottomNavItem | null;
   variant?: AppBottomNavVariant;
-  privateRoomLabel: string;
+  privateZoneLabel: string;
   onChatClick: () => void;
-  onPrivateRoomClick: () => void;
+  onPrivateZoneClick: () => void;
+  onMenuClick: () => void;
 }
 
 export function AppBottomNav({
   activeItem = null,
   variant = "warm",
-  privateRoomLabel,
+  privateZoneLabel,
   onChatClick,
-  onPrivateRoomClick,
+  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_room"
-        data-analytics-label="Private room navigation"
-        className={getButtonClass(activeItem === "privateRoom")}
-        aria-current={activeItem === "privateRoom" ? "page" : undefined}
-        onClick={onPrivateRoomClick}
+        data-analytics-key="navigation.private_zone"
+        data-analytics-label="Private Zone navigation"
+        className={getButtonClass(activeItem === "privateZone")}
+        aria-current={activeItem === "privateZone" ? "page" : undefined}
+        onClick={onPrivateZoneClick}
       >
         <Camera size={20} aria-hidden="true" />
-        <span>{privateRoomLabel}</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/_components/core/modal-portal.tsx

@@ -20,7 +20,10 @@ export interface ModalPortalProps {
   scrimOpacity: number;
   panelStyle?: CSSProperties;
   persistent?: boolean;
+  role?: "dialog" | "alertdialog";
   ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
 }
 
 export function ModalPortal({
@@ -32,7 +35,10 @@ export function ModalPortal({
   scrimOpacity,
   panelStyle,
   persistent = false,
+  role = "dialog",
   ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
 }: ModalPortalProps) {
   useEffect(() => {
     if (!open || typeof document === "undefined") return;
@@ -63,9 +69,11 @@ export function ModalPortal({
       onClick={handleScrimClick}
     >
       <div
-        role="dialog"
+        role={role}
         aria-modal="true"
         aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
         className={panelClassName}
         style={panelStyle}
         onClick={(event) => event.stopPropagation()}

src/app/_components/index.ts

@@ -3,5 +3,6 @@
  */
 
 export * from "./back-button";
+export * from "./avatar-interaction";
 export * from "./character-avatar";
 export * from "./user-message-avatar";

src/app/_components/payment/__tests__/external-browser-checkout-button.test.tsx

@@ -0,0 +1,77 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createCheckoutHandoff, openUrlWithExternalBrowser } = vi.hoisted(
+  () => ({
+    createCheckoutHandoff: vi.fn(),
+    openUrlWithExternalBrowser: vi.fn(),
+  }),
+);
+
+vi.mock("@/lib/auth/checkout_handoff", () => ({ createCheckoutHandoff }));
+vi.mock("@/utils/url-launcher-util", () => ({
+  UrlLauncherUtil: { openUrlWithExternalBrowser },
+}));
+vi.mock("@/utils/browser-detect", () => ({
+  BrowserDetector: { isFacebookInAppBrowser: () => true },
+}));
+
+import { ExternalBrowserCheckoutButton } from "../external-browser-checkout-button";
+
+describe("ExternalBrowserCheckoutButton", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    createCheckoutHandoff.mockResolvedValue({
+      success: true,
+      data: {
+        externalUrl:
+          "https://cozsweet.com/external-entry?target=checkout&handoffToken=opaque",
+        expiresAt: "2026-07-28T16:00:00+00:00",
+      },
+    });
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it("creates only a handoff before opening the external browser", async () => {
+    await act(async () => {
+      root.render(
+        <ExternalBrowserCheckoutButton
+          characterSlug="maya"
+          checkoutIntent={{
+            planId: "vip_monthly",
+            autoRenew: true,
+            commercialOfferId: "offer-1",
+          }}
+        />,
+      );
+    });
+
+    const button = container.querySelector("button");
+    expect(button?.textContent).toContain(
+      "Open in browser for more payment methods",
+    );
+    await act(async () => button?.click());
+
+    expect(createCheckoutHandoff).toHaveBeenCalledWith({
+      planId: "vip_monthly",
+      autoRenew: true,
+      commercialOfferId: "offer-1",
+    });
+    expect(openUrlWithExternalBrowser).toHaveBeenCalledWith(
+      "https://cozsweet.com/external-entry?target=checkout&handoffToken=opaque&character=maya",
+    );
+  });
+});

src/app/_components/payment/__tests__/payment-launch-dialogs.test.tsx

@@ -1,23 +1,49 @@
-import { renderToStaticMarkup } from "react-dom/server";
-import { describe, expect, it, vi } from "vitest";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { PaymentLaunchDialogs } from "../payment-launch-dialogs";
 
 const hiddenLaunch = {
   handleEzpayCancel: vi.fn(),
   handleEzpayConfirm: vi.fn(),
+  handleRegionalQrClose: vi.fn(),
   handleStripeClose: vi.fn(),
   handleStripeConfirmed: vi.fn(),
   isConfirmingEzpay: false,
+  regionalQrErrorMessage: null,
+  regionalQrPayment: null,
+  regionalQrStatus: null,
   shouldShowEzpayConfirmDialog: false,
+  shouldShowRegionalQrDialog: false,
   shouldShowStripeDialog: false,
   stripeClientSecret: null,
+  stripeCustomerSessionClientSecret: null,
+  savedPaymentMethodsEnabled: false,
 };
 
 describe("PaymentLaunchDialogs", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    container.style.transform = "translateX(50%)";
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
   it("renders nothing when neither payment dialog is active", () => {
-    expect(
-      renderToStaticMarkup(
+    act(() =>
+      root.render(
         <PaymentLaunchDialogs
           currentOrderId={null}
           externalCheckoutAnalyticsKey="payment.external_checkout"
@@ -25,11 +51,15 @@ describe("PaymentLaunchDialogs", () => {
           launch={hiddenLaunch}
         />,
       ),
-    ).toBe("");
+    );
+
+    expect(document.body.querySelector('[role="dialog"]')).toBeNull();
+    expect(document.body.querySelector('[role="alertdialog"]')).toBeNull();
   });
 
-  it("renders the shared Ezpay confirmation content", () => {
-    const html = renderToStaticMarkup(
+  it("portals the shared Ezpay confirmation outside transformed checkout UI", () => {
+    act(() =>
+      root.render(
         <PaymentLaunchDialogs
           currentOrderId="order-123"
           externalCheckoutAnalyticsKey="tip.external_checkout"
@@ -40,13 +70,126 @@ describe("PaymentLaunchDialogs", () => {
             shouldShowEzpayConfirmDialog: true,
           }}
         />,
+      ),
     );
 
-    expect(html).toContain('role="alertdialog"');
-    expect(html).toContain("Continue to GCash?");
-    expect(html).toContain("Your coffee order is ready.");
-    expect(html).toContain("Order No. order-123");
-    expect(html).toContain('data-analytics-key="tip.external_checkout"');
-    expect(html).toContain("Opening...");
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.parentElement?.parentElement).toBe(document.body);
+    expect(dialog?.textContent).toContain("Continue to payment?");
+    expect(dialog?.textContent).toContain("Your coffee order is ready.");
+    expect(dialog?.textContent).toContain("Order No. order-123");
+    expect(
+      dialog?.querySelector("button[data-analytics-key]")?.getAttribute(
+        "data-analytics-key",
+      ),
+    ).toBe("tip.external_checkout");
+    expect(dialog?.textContent).toContain("Opening...");
+    expect(document.body.style.overflow).toBe("hidden");
+  });
+
+  it("portals an accessible QRIS dialog with display cents and order status", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-id-qris"
+          externalCheckoutAnalyticsKey="tip.external_checkout"
+          ezpayDescription="Scan QRIS to finish the payment."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrPayment: {
+              qrData: "00020101021226670016COM.NOBUBANK.WWW",
+              orderId: "order-id-qris",
+              amountCents: 5_000_000,
+              currency: "IDR",
+              experience: "qris",
+            },
+            regionalQrStatus: "pending",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Scan to pay with QRIS");
+    expect(dialog?.querySelector("svg title")?.textContent).toBe(
+      "QRIS payment QR code",
+    );
+    expect(dialog?.textContent).toContain("Order No. order-id-qris");
+    expect(dialog?.textContent).toContain("Rp");
+    expect(dialog?.textContent).toContain("50.000");
+    expect(dialog?.textContent).toContain("Waiting for payment");
+  });
+
+  it("labels a Philippine QR fallback as GCash / QR Ph", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-ph-qr"
+          externalCheckoutAnalyticsKey="payment.external_checkout"
+          ezpayDescription="Pay with GCash."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrPayment: {
+              qrData: "000201010212ph-qr-payload",
+              orderId: "order-ph-qr",
+              amountCents: 49_990,
+              currency: "PHP",
+              experience: "gcashQrPh",
+            },
+            regionalQrStatus: "pending",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain("Pay with GCash / QR Ph");
+    expect(dialog?.textContent).not.toContain("QRIS");
+    expect(dialog?.querySelector("svg title")?.textContent).toBe(
+      "GCash / QR Ph payment QR code",
+    );
+    expect(dialog?.textContent).toContain("₱");
+
+    const closeButton = Array.from(
+      dialog?.querySelectorAll("button") ?? [],
+    ).find((button) => button.textContent?.trim() === "Close");
+    act(() => closeButton?.click());
+    expect(hiddenLaunch.handleRegionalQrClose).toHaveBeenCalledOnce();
+  });
+
+  it("shows QRIS failure state and handles empty QR data safely", () => {
+    act(() =>
+      root.render(
+        <PaymentLaunchDialogs
+          currentOrderId="order-id-qris"
+          externalCheckoutAnalyticsKey="payment.external_checkout"
+          ezpayDescription="Scan QRIS to finish the payment."
+          launch={{
+            ...hiddenLaunch,
+            regionalQrErrorMessage: "Payment failed or was cancelled.",
+            regionalQrPayment: {
+              qrData: "",
+              orderId: "order-id-qris",
+              amountCents: 5_000_000,
+              currency: "IDR",
+              experience: "qris",
+            },
+            regionalQrStatus: "failed",
+            shouldShowRegionalQrDialog: true,
+          }}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog?.textContent).toContain("QRIS data is unavailable");
+    expect(dialog?.textContent).toContain("Payment failed or was cancelled.");
+    expect(dialog?.textContent).toContain("Close");
   });
 });

src/app/_components/payment/__tests__/payment-method-selector.test.tsx

@@ -62,6 +62,27 @@ describe("PaymentMethodSelector", () => {
     );
   });
 
+  it("labels Indonesia Ezpay as QRIS without the GCash logo", () => {
+    const html = renderToStaticMarkup(
+      <PaymentMethodSelector
+        config={{
+          canChoosePaymentMethod: true,
+          initialPayChannel: "ezpay",
+          showPaymentMethodSelector: true,
+          ezpayDisplayName: "QRIS",
+        }}
+        value="ezpay"
+        caption="QRIS by default in Indonesia"
+        analyticsKey="subscription.payment_method"
+        onChange={() => undefined}
+      />,
+    );
+
+    expect(html).toContain('aria-label="QRIS"');
+    expect(html).toContain("QRIS by default in Indonesia");
+    expect(html).not.toContain("gcash-logo.svg");
+  });
+
   it("renders compact controls without the caption", () => {
     const html = renderToStaticMarkup(
       <PaymentMethodSelector
@@ -81,7 +102,7 @@ describe("PaymentMethodSelector", () => {
     expect(html).toContain('data-density="compact"');
     expect(html).toContain("Payment Method");
     expect(html).not.toContain("This caption is hidden");
-    expect(html).toContain("min-h-11");
+    expect(html).toContain("min-h-13");
   });
 
   it("does not render when payment method selection is unavailable", () => {

src/app/_components/payment/__tests__/stripe-payment-dialog.test.tsx

@@ -0,0 +1,163 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const stripeConfirmPayment = vi.fn(async () => ({}));
+const elementsSubmit = vi.fn(async () => ({}));
+let capturedElementsOptions: Record<string, unknown> | null = null;
+let capturedExpressProps: Record<string, unknown> | null = null;
+let capturedPaymentProps: Record<string, unknown> | null = null;
+
+vi.hoisted(() => {
+  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY = "pk_test_checkout";
+});
+
+vi.mock("@stripe/stripe-js", () => ({
+  loadStripe: vi.fn(() => Promise.resolve({})),
+}));
+
+vi.mock("@stripe/react-stripe-js", () => ({
+  Elements: ({
+    children,
+    options,
+  }: {
+    children: React.ReactNode;
+    options: Record<string, unknown>;
+  }) => {
+    capturedElementsOptions = options;
+    return <>{children}</>;
+  },
+  ExpressCheckoutElement: (props: Record<string, unknown>) => {
+    capturedExpressProps = props;
+    return <div data-testid="express-checkout" />;
+  },
+  PaymentElement: (props: Record<string, unknown>) => {
+    capturedPaymentProps = props;
+    return <div data-testid="payment-element" />;
+  },
+  useElements: () => ({ submit: elementsSubmit }),
+  useStripe: () => ({ confirmPayment: stripeConfirmPayment }),
+}));
+
+import { StripePaymentDialog } from "../stripe-payment-dialog";
+
+describe("StripePaymentDialog", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    capturedElementsOptions = null;
+    capturedExpressProps = null;
+    capturedPaymentProps = null;
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+      .IS_REACT_ACT_ENVIRONMENT = true;
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    document.body.style.overflow = "";
+  });
+
+  it("renders Express Checkout first and a collapsed Pay by card section last", () => {
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="pi_123_secret_payment"
+          customerSessionClientSecret="cuss_123_secret_saved"
+          savedPaymentMethodsEnabled
+          onClose={vi.fn()}
+        />,
+      ),
+    );
+
+    expect(capturedElementsOptions).toMatchObject({
+      clientSecret: "pi_123_secret_payment",
+      customerSessionClientSecret: "cuss_123_secret_saved",
+    });
+    expect(capturedExpressProps?.options).toMatchObject({
+      paymentMethodOrder: [
+        "apple_pay",
+        "google_pay",
+        "link",
+        "paypal",
+        "amazon_pay",
+        "klarna",
+      ],
+      paymentMethods: {
+        applePay: "always",
+        googlePay: "always",
+        link: "auto",
+        paypal: "auto",
+        amazonPay: "auto",
+        klarna: "auto",
+      },
+    });
+    expect(capturedPaymentProps?.options).toMatchObject({
+      layout: { type: "accordion", defaultCollapsed: true },
+      paymentMethodOrder: ["card"],
+      wallets: { applePay: "never", googlePay: "never", link: "never" },
+    });
+    const text = document.body.textContent ?? "";
+    expect(text).toContain("Pay by card");
+    const express = document.body.querySelector('[data-testid="express-checkout"]');
+    const card = document.body.querySelector('[data-testid="payment-element"]');
+    expect(express).not.toBeNull();
+    expect(card).not.toBeNull();
+    expect(
+      express!.compareDocumentPosition(card!) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("does not pass an invalid or disabled Customer Session secret", () => {
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="pi_123_secret_payment"
+          customerSessionClientSecret="invalid"
+          savedPaymentMethodsEnabled={false}
+          onClose={vi.fn()}
+        />,
+      ),
+    );
+
+    expect(capturedElementsOptions).not.toHaveProperty(
+      "customerSessionClientSecret",
+    );
+  });
+
+  it("uses the same confirmation path for an Express Checkout approval", async () => {
+    const onConfirmed = vi.fn();
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="pi_123_secret_payment"
+          onClose={vi.fn()}
+          onConfirmed={onConfirmed}
+        />,
+      ),
+    );
+
+    const onConfirm = capturedExpressProps?.onConfirm as
+      | ((event: { paymentFailed: ReturnType<typeof vi.fn> }) => Promise<void>)
+      | undefined;
+    expect(onConfirm).toBeTypeOf("function");
+    await act(async () => {
+      await onConfirm?.({ paymentFailed: vi.fn() });
+    });
+
+    expect(stripeConfirmPayment).toHaveBeenCalledTimes(1);
+    expect(stripeConfirmPayment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        elements: expect.any(Object),
+        redirect: "if_required",
+      }),
+    );
+    expect(onConfirmed).toHaveBeenCalledTimes(1);
+  });
+});

src/app/_components/payment/external-browser-checkout-button.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import { useState, useSyncExternalStore } from "react";
+
+import type { CheckoutIntent } from "@/data/schemas/auth";
+import {
+  DEFAULT_CHARACTER_SLUG,
+  getCharacterBySlug,
+} from "@/data/constants/character";
+import { createCheckoutHandoff } from "@/lib/auth/checkout_handoff";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { ExceptionHandler } from "@/core/errors";
+import { Result } from "@/utils/result";
+import { UrlLauncherUtil } from "@/utils/url-launcher-util";
+
+export interface ExternalBrowserCheckoutButtonProps {
+  checkoutIntent: CheckoutIntent;
+  disabled?: boolean;
+  characterSlug?: string;
+}
+
+export function ExternalBrowserCheckoutButton({
+  checkoutIntent,
+  disabled = false,
+  characterSlug = DEFAULT_CHARACTER_SLUG,
+}: ExternalBrowserCheckoutButtonProps) {
+  const isFacebookBrowser = useSyncExternalStore(
+    () => () => undefined,
+    () => BrowserDetector.isFacebookInAppBrowser(),
+    () => false,
+  );
+  const [isOpening, setIsOpening] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  if (!isFacebookBrowser) return null;
+
+  const handleOpen = async () => {
+    if (disabled || isOpening) return;
+    setIsOpening(true);
+    setErrorMessage(null);
+    const result = await createCheckoutHandoff(checkoutIntent);
+    if (Result.isErr(result)) {
+      setErrorMessage(
+        ExceptionHandler.message(
+          result.error,
+          "Could not open this checkout in your browser. Please sign in and try again.",
+        ),
+      );
+      setIsOpening(false);
+      return;
+    }
+    try {
+      const verifiedCharacter =
+        getCharacterBySlug(characterSlug)?.slug ?? DEFAULT_CHARACTER_SLUG;
+      const externalUrl = new URL(
+        result.data.externalUrl,
+        window.location.origin,
+      );
+      externalUrl.searchParams.set("character", verifiedCharacter);
+      UrlLauncherUtil.openUrlWithExternalBrowser(externalUrl.toString());
+    } catch (error) {
+      setErrorMessage(
+        ExceptionHandler.message(
+          error,
+          "Could not open this checkout in your browser. Please try again.",
+        ),
+      );
+      setIsOpening(false);
+    }
+  };
+
+  return (
+    <div className="mb-2 w-full text-center">
+      <button
+        type="button"
+        className="min-h-11 w-full cursor-pointer rounded-full border border-black/15 bg-white px-4 py-2.5 text-sm font-semibold text-text-foreground disabled:cursor-not-allowed disabled:opacity-55"
+        disabled={disabled || isOpening}
+        onClick={() => void handleOpen()}
+      >
+        {isOpening
+          ? "Opening browser..."
+          : "Open in browser for more payment methods"}
+      </button>
+      {errorMessage ? (
+        <p className="mt-2 text-sm text-[#c0392b]" role="alert">
+          {errorMessage}
+        </p>
+      ) : null}
+    </div>
+  );
+}

src/app/_components/payment/lazy-stripe-payment-dialog.tsx

@@ -2,6 +2,8 @@
 
 import dynamic from "next/dynamic";
 
+import { ModalPortal } from "@/app/_components/core/modal-portal";
+
 import type { StripePaymentDialogProps } from "./stripe-payment-dialog";
 import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles";
 
@@ -20,22 +22,28 @@ export function LazyStripePaymentDialog(props: StripePaymentDialogProps) {
   return <StripePaymentDialog {...props} />;
 }
 
-function StripePaymentDialogLoading() {
+export function StripePaymentDialogLoading() {
   return (
-    <div
-      className={styles.overlay}
-      role="dialog"
-      aria-modal="true"
-      aria-labelledby="stripe-payment-loading-title"
+    <ModalPortal
+      open
+      persistent
+      onClose={() => undefined}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
+      ariaLabelledBy="stripe-payment-loading-title"
+      ariaDescribedBy="stripe-payment-loading-description"
     >
-      <div className={styles.dialog} aria-busy="true">
+      <div aria-busy="true">
         <div className={styles.header}>
           <h2 id="stripe-payment-loading-title" className={styles.title}>
             Preparing secure payment
           </h2>
-          <p className={styles.content}>Loading payment methods...</p>
-        </div>
+          <p id="stripe-payment-loading-description" className={styles.content}>
+            Loading payment methods...
+          </p>
         </div>
       </div>
+    </ModalPortal>
   );
 }

src/app/_components/payment/payment-launch-dialogs.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import { useId, type ReactNode } from "react";
+import { QRCodeSVG } from "qrcode.react";
 
+import { ModalPortal } from "@/app/_components/core/modal-portal";
 import type { PaymentLaunchFlow } from "@/app/_hooks/use-payment-launch-flow";
 
 import { LazyStripePaymentDialog } from "./lazy-stripe-payment-dialog";
@@ -11,12 +13,19 @@ type PaymentLaunchDialogFlow = Pick<
   PaymentLaunchFlow,
   | "handleEzpayCancel"
   | "handleEzpayConfirm"
+  | "handleRegionalQrClose"
   | "handleStripeClose"
   | "handleStripeConfirmed"
   | "isConfirmingEzpay"
+  | "regionalQrErrorMessage"
+  | "regionalQrPayment"
+  | "regionalQrStatus"
   | "shouldShowEzpayConfirmDialog"
+  | "shouldShowRegionalQrDialog"
   | "shouldShowStripeDialog"
   | "stripeClientSecret"
+  | "stripeCustomerSessionClientSecret"
+  | "savedPaymentMethodsEnabled"
 >;
 
 export interface PaymentLaunchDialogsProps {
@@ -46,9 +55,21 @@ export function PaymentLaunchDialogs({
           onConfirm={launch.handleEzpayConfirm}
         />
       ) : null}
+      {launch.shouldShowRegionalQrDialog && launch.regionalQrPayment ? (
+        <RegionalQrPaymentDialog
+          payment={launch.regionalQrPayment}
+          status={launch.regionalQrStatus}
+          errorMessage={launch.regionalQrErrorMessage}
+          onClose={launch.handleRegionalQrClose}
+        />
+      ) : null}
       {launch.shouldShowStripeDialog && launch.stripeClientSecret ? (
         <LazyStripePaymentDialog
           clientSecret={launch.stripeClientSecret}
+          customerSessionClientSecret={
+            launch.stripeCustomerSessionClientSecret
+          }
+          savedPaymentMethodsEnabled={launch.savedPaymentMethodsEnabled}
           returnPath={stripeReturnPath}
           onClose={launch.handleStripeClose}
           onConfirmed={launch.handleStripeConfirmed}
@@ -58,6 +79,151 @@ export function PaymentLaunchDialogs({
   );
 }
 
+interface RegionalQrPaymentDialogProps {
+  errorMessage: string | null;
+  onClose: () => void;
+  payment: NonNullable<PaymentLaunchFlow["regionalQrPayment"]>;
+  status: PaymentLaunchFlow["regionalQrStatus"];
+}
+
+function formatRegionalQrAmount(amountCents: number, currency: string): string {
+  const normalizedCurrency = currency.trim().toUpperCase() || "IDR";
+  try {
+    return new Intl.NumberFormat(
+      normalizedCurrency === "PHP" ? "en-PH" : "id-ID",
+      {
+        style: "currency",
+        currency: normalizedCurrency,
+        maximumFractionDigits: normalizedCurrency === "IDR" ? 0 : 2,
+      },
+    ).format(amountCents / 100);
+  } catch {
+    return `${normalizedCurrency} ${(amountCents / 100).toFixed(2)}`;
+  }
+}
+
+function regionalQrStatusMessage(
+  status: PaymentLaunchFlow["regionalQrStatus"],
+  errorMessage: string | null,
+  paymentName: string,
+): string {
+  if (status === "failed") {
+    return errorMessage || "Payment failed. Please try again.";
+  }
+  if (status === "expired") {
+    return errorMessage || `This ${paymentName} order has expired.`;
+  }
+  return "Waiting for payment";
+}
+
+function RegionalQrPaymentDialog({
+  errorMessage,
+  onClose,
+  payment,
+  status,
+}: RegionalQrPaymentDialogProps) {
+  const titleId = useId();
+  const copy = regionalQrCopy(payment.experience);
+  const statusMessage = regionalQrStatusMessage(
+    status,
+    errorMessage,
+    copy.paymentName,
+  );
+
+  return (
+    <ModalPortal
+      open
+      persistent
+      onClose={onClose}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
+      ariaLabelledBy={titleId}
+    >
+      <div className={`${styles.header} text-center`}>
+        <h2 id={titleId} className={styles.title}>
+          {copy.title}
+        </h2>
+        <p className={styles.content}>
+          {copy.description}
+        </p>
+      </div>
+      <div className="mb-4 flex min-h-64 items-center justify-center rounded-2xl bg-white p-4">
+        {payment.qrData ? (
+          <QRCodeSVG
+            value={payment.qrData}
+            title={copy.qrTitle}
+            size={256}
+            level="M"
+            marginSize={2}
+            className="h-auto w-full max-w-64"
+          />
+        ) : (
+          <p className={styles.error} role="alert">
+            {copy.unavailableMessage}
+          </p>
+        )}
+      </div>
+      <div className="mb-4 flex flex-col gap-2 text-center">
+        <p className={styles.content}>Order No. {payment.orderId}</p>
+        <p className="m-0 text-xl font-bold text-text-foreground">
+          {formatRegionalQrAmount(payment.amountCents, payment.currency)}
+        </p>
+        <p
+          className={status === "failed" || status === "expired" ? styles.error : styles.content}
+          role="status"
+        >
+          {statusMessage}
+        </p>
+      </div>
+      <div className={styles.actions}>
+        <button
+          type="button"
+          className={`${styles.button} ${styles.secondary}`}
+          onClick={onClose}
+        >
+          Close
+        </button>
+      </div>
+    </ModalPortal>
+  );
+}
+
+function regionalQrCopy(
+  experience: NonNullable<PaymentLaunchFlow["regionalQrPayment"]>["experience"],
+) {
+  if (experience === "gcashQrPh") {
+    return {
+      paymentName: "GCash / QR Ph",
+      title: "Pay with GCash / QR Ph",
+      description:
+        "Open GCash or another QR Ph-compatible app and scan this code.",
+      qrTitle: "GCash / QR Ph payment QR code",
+      unavailableMessage:
+        "GCash / QR Ph data is unavailable. Please close this dialog and try again.",
+    };
+  }
+  if (experience === "qris") {
+    return {
+      paymentName: "QRIS",
+      title: "Scan to pay with QRIS",
+      description:
+        "Open a QRIS-compatible banking or wallet app and scan this code.",
+      qrTitle: "QRIS payment QR code",
+      unavailableMessage:
+        "QRIS data is unavailable. Please close this dialog and try again.",
+    };
+  }
+  return {
+    paymentName: "payment QR",
+    title: "Scan to pay",
+    description: "Open a compatible banking or wallet app and scan this code.",
+    qrTitle: "Payment QR code",
+    unavailableMessage:
+      "Payment QR data is unavailable. Please close this dialog and try again.",
+  };
+}
+
 interface EzpayRedirectConfirmDialogProps {
   description: ReactNode;
   externalCheckoutAnalyticsKey: string;
@@ -78,16 +244,19 @@ function EzpayRedirectConfirmDialog({
   const titleId = useId();
 
   return (
-    <div
-      className={styles.overlay}
+    <ModalPortal
+      open
+      persistent
+      onClose={onCancel}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
       role="alertdialog"
-      aria-modal="true"
-      aria-labelledby={titleId}
+      ariaLabelledBy={titleId}
     >
-      <div className={styles.dialog}>
       <div className={styles.header}>
         <h2 id={titleId} className={styles.title}>
-            Continue to GCash?
+          Continue to payment?
         </h2>
         <p className={styles.content}>{description}</p>
         <p className={styles.content}>Order No. {orderId}</p>
@@ -112,7 +281,6 @@ function EzpayRedirectConfirmDialog({
           {isConfirming ? "Opening..." : "Continue"}
         </button>
       </div>
-      </div>
-    </div>
+    </ModalPortal>
   );
 }

src/app/_components/payment/payment-method-selector.tsx

@@ -44,17 +44,28 @@ export function PaymentMethodSelector({
 }: PaymentMethodSelectorProps) {
   if (!config.showPaymentMethodSelector) return null;
   const isCompact = density === "compact";
+  const ezpayDisplayName = config.ezpayDisplayName ?? "GCash";
+  const configuredPaymentMethods = PAYMENT_METHODS.map((method) =>
+    method.channel === "ezpay"
+      ? {
+          ...method,
+          title: ezpayDisplayName,
+          logoSrc:
+            ezpayDisplayName === "GCash" ? method.logoSrc : undefined,
+        }
+      : method,
+  );
 
   const paymentMethods =
     config.initialPayChannel === "ezpay"
-      ? [...PAYMENT_METHODS].sort((a, b) =>
+      ? [...configuredPaymentMethods].sort((a, b) =>
           a.channel === "ezpay" ? -1 : b.channel === "ezpay" ? 1 : 0,
         )
-      : PAYMENT_METHODS;
+      : configuredPaymentMethods;
 
   return (
     <section
-      className={`flex flex-col ${isCompact ? "gap-1.5" : "gap-[clamp(8px,1.852vw,10px)]"} ${className ?? ""}`.trim()}
+      className={`flex flex-col ${isCompact ? "gap-2" : "gap-[clamp(8px,1.852vw,10px)]"} ${className ?? ""}`.trim()}
       data-density={density}
       aria-labelledby="payment-method-title"
     >
@@ -63,7 +74,7 @@ export function PaymentMethodSelector({
       >
         <h2
           id="payment-method-title"
-          className={`m-0 font-bold leading-[1.2] text-auth-text-primary ${isCompact ? "text-sm" : "text-(length:--responsive-card-title,var(--font-size-lg))"}`}
+          className={`m-0 font-bold leading-[1.2] text-auth-text-primary ${isCompact ? "text-base" : "text-(length:--responsive-card-title,var(--font-size-lg))"}`}
           style={{ fontFamily: "var(--font-athelas), var(--font-system)" }}
         >
           Payment Method
@@ -78,7 +89,7 @@ export function PaymentMethodSelector({
         {paymentMethods.map((method) => {
           const selected = method.channel === value;
           const classes = [
-            `flex cursor-pointer items-center justify-center text-center font-[inherit] text-[#3c3b3b] transition-[border-color,box-shadow,transform] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent active:enabled:scale-98 disabled:cursor-not-allowed disabled:opacity-72 ${isCompact ? "min-h-11 rounded-2xl px-2 py-1.5" : "min-h-[clamp(54px,11.481vw,62px)] rounded-(--responsive-card-radius-sm,18px) px-[clamp(12px,2.593vw,14px)] py-[clamp(9px,1.852vw,10px)]"}`,
+            `flex cursor-pointer items-center justify-center text-center font-[inherit] text-[#3c3b3b] transition-[border-color,box-shadow,transform] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent active:enabled:scale-98 disabled:cursor-not-allowed disabled:opacity-72 ${isCompact ? "min-h-13 rounded-[18px] px-3 py-2" : "min-h-[clamp(54px,11.481vw,62px)] rounded-(--responsive-card-radius-sm,18px) px-[clamp(12px,2.593vw,14px)] py-[clamp(9px,1.852vw,10px)]"}`,
             selected
               ? "border-2 border-[#f657a0] bg-[#fff4f9] shadow-[0_8px_18px_rgba(217,47,127,0.24),0_0_0_3px_rgba(217,47,127,0.18)] -translate-y-0.5"
               : "border border-[rgba(246,87,160,0.18)] bg-white shadow-[0_5px_7px_0_rgba(247,89,168,0.08)]",
@@ -105,7 +116,7 @@ export function PaymentMethodSelector({
                   aria-hidden="true"
                   width={122}
                   height={29}
-                  className={`block object-contain ${isCompact ? "max-h-7 w-[min(100%,80px)]" : "max-h-8.5 w-[min(100%,92px)]"}`}
+                  className={`block object-contain ${isCompact ? "max-h-8 w-[min(100%,92px)]" : "max-h-8.5 w-[min(100%,92px)]"}`}
                 />
               ) : (
                 <span className="text-(length:--responsive-body,16px) font-bold leading-[1.1] text-[#1e1e1e]">

src/app/_components/payment/stripe-payment-dialog.styles.ts

@@ -2,13 +2,18 @@ export const stripePaymentDialogStyles = {
   overlay:
     "fixed inset-0 z-70 flex items-center justify-center bg-[rgba(0,0,0,0.5)] pb-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-bottom,0))] pl-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-left,0))] pr-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-right,0))] pt-[calc(var(--dialog-safe-margin,20px)+var(--app-safe-top,0))]",
   dialog:
-    "max-h-[calc(var(--app-visible-height,100dvh)-calc(var(--dialog-safe-margin,20px)*2))] w-full max-w-(--dialog-wide-max-width,420px) overflow-y-auto rounded-(--responsive-card-radius,32px) bg-(--color-page-background,#ffffff) px-(--responsive-card-padding,18px) pb-(--responsive-card-padding,18px) pt-(--responsive-card-padding-lg,24px) shadow-[0_18px_40px_rgba(0,0,0,0.16)]",
+    "max-h-[calc(var(--app-visible-height,100dvh)-calc(var(--dialog-safe-margin,20px)*2))] w-full max-w-(--dialog-wide-max-width,420px) overflow-y-auto overscroll-contain rounded-(--responsive-card-radius,32px) bg-(--color-page-background,#ffffff) px-(--responsive-card-padding,18px) pb-(--responsive-card-padding,18px) pt-(--responsive-card-padding-lg,24px) shadow-[0_18px_40px_rgba(0,0,0,0.16)]",
   header: "mb-(--page-section-gap,18px) text-left",
   title:
     "m-0 mb-[clamp(7px,1.481vw,8px)] text-(length:--responsive-page-title,22px) font-bold leading-[1.2] text-text-foreground",
   content:
     "m-0 text-(length:--responsive-body,14px) leading-normal text-[#393939]",
   form: "flex flex-col gap-(--page-section-gap,18px)",
+  expressSection: "w-full empty:hidden",
+  cardSection:
+    "flex w-full flex-col gap-(--spacing-sm,8px) border-t border-black/10 pt-(--page-section-gap,18px)",
+  cardTitle:
+    "m-0 text-(length:--responsive-body,16px) font-semibold text-text-foreground",
   error:
     "m-0 text-(length:--responsive-caption,13px) leading-[1.45] text-[#c0392b]",
   actions: "flex w-full gap-(--spacing-md,12px)",

src/app/_components/payment/stripe-payment-dialog.tsx

@@ -4,18 +4,28 @@
  *
  * 后端当前返回 PaymentIntent clientSecret，因此这里直接用它完成前端确认。
  */
-import { useState, type FormEvent } from "react";
+import { useEffect, useId, useRef, useState, type FormEvent } from "react";
 import {
   Elements,
+  ExpressCheckoutElement,
   PaymentElement,
   useElements,
   useStripe,
 } from "@stripe/react-stripe-js";
-import { loadStripe } from "@stripe/stripe-js";
+import {
+  loadStripe,
+  type AvailablePaymentMethods,
+  type StripeExpressCheckoutElementConfirmEvent,
+} from "@stripe/stripe-js";
 
+import { ModalPortal } from "@/app/_components/core/modal-portal";
 import { ExceptionHandler } from "@/core/errors";
 import { ROUTES } from "@/router/routes";
 import { Logger } from "@/utils/logger";
+import { BrowserDetector } from "@/utils/browser-detect";
+import { PlatformDetector } from "@/utils/platform-detect";
+import { getStripeCustomerSessionClientSecret } from "@/lib/payment/payment_launch";
+import { behaviorAnalytics } from "@/lib/analytics";
 
 import { stripePaymentDialogStyles as styles } from "./stripe-payment-dialog.styles";
 
@@ -25,8 +35,16 @@ const stripePromise = stripePublishableKey
   ? loadStripe(stripePublishableKey)
   : null;
 
+type ExpressAvailabilityValue = boolean | { available: boolean } | undefined;
+
+function isExpressMethodAvailable(value: ExpressAvailabilityValue): boolean {
+  return value === true || (typeof value === "object" && value.available);
+}
+
 export interface StripePaymentDialogProps {
   clientSecret: string;
+  customerSessionClientSecret?: string | null;
+  savedPaymentMethodsEnabled?: boolean;
   returnPath?: string;
   onClose: () => void;
   onConfirmed?: () => void;
@@ -34,17 +52,38 @@ export interface StripePaymentDialogProps {
 
 export function StripePaymentDialog({
   clientSecret,
+  customerSessionClientSecret = null,
+  savedPaymentMethodsEnabled = false,
   returnPath = ROUTES.subscription + "/success",
   onClose,
   onConfirmed,
 }: StripePaymentDialogProps) {
+  const titleId = useId();
+  const descriptionId = useId();
+  const savedCardClientSecret = getStripeCustomerSessionClientSecret({
+    provider: "stripe",
+    customerSessionClientSecret,
+    savedPaymentMethodsEnabled,
+  });
+
   if (!stripePromise) {
     return (
-      <div className={styles.overlay} role="alertdialog" aria-modal="true">
-        <div className={styles.dialog}>
+      <ModalPortal
+        open
+        persistent
+        onClose={onClose}
+        scrimClassName={styles.overlay}
+        panelClassName={styles.dialog}
+        scrimOpacity={0.5}
+        role="alertdialog"
+        ariaLabelledBy={titleId}
+        ariaDescribedBy={descriptionId}
+      >
         <div className={styles.header}>
-            <h2 className={styles.title}>Payment unavailable</h2>
-            <p className={styles.content}>
+          <h2 id={titleId} className={styles.title}>
+            Payment unavailable
+          </h2>
+          <p id={descriptionId} className={styles.content}>
             Stripe publishable key is not configured for this build.
           </p>
         </div>
@@ -57,24 +96,26 @@ export function StripePaymentDialog({
             OK
           </button>
         </div>
-        </div>
-      </div>
+      </ModalPortal>
     );
   }
 
   return (
-    <div
-      className={styles.overlay}
-      role="dialog"
-      aria-modal="true"
-      aria-labelledby="stripe-payment-title"
+    <ModalPortal
+      open
+      persistent
+      onClose={onClose}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
+      ariaLabelledBy={titleId}
+      ariaDescribedBy={descriptionId}
     >
-      <div className={styles.dialog}>
       <div className={styles.header}>
-          <h2 id="stripe-payment-title" className={styles.title}>
+        <h2 id={titleId} className={styles.title}>
           Complete payment
         </h2>
-          <p className={styles.content}>
+        <p id={descriptionId} className={styles.content}>
           Enter your payment details securely through Stripe.
         </p>
       </div>
@@ -83,6 +124,9 @@ export function StripePaymentDialog({
         stripe={stripePromise}
         options={{
           clientSecret,
+          ...(savedCardClientSecret
+            ? { customerSessionClientSecret: savedCardClientSecret }
+            : {}),
           appearance: {
             theme: "stripe",
             variables: {
@@ -99,8 +143,7 @@ export function StripePaymentDialog({
           onConfirmed={onConfirmed}
         />
       </Elements>
-      </div>
-    </div>
+    </ModalPortal>
   );
 }
 
@@ -116,6 +159,20 @@ function StripePaymentForm({
   const elements = useElements();
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
+  const submittingRef = useRef(false);
+  const [hasExpressPaymentMethods, setHasExpressPaymentMethods] = useState<
+    boolean | null
+  >(null);
+  const [expressMaxColumns, setExpressMaxColumns] = useState(1);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return;
+    const query = window.matchMedia("(min-width: 640px)");
+    const updateColumns = () => setExpressMaxColumns(query.matches ? 2 : 1);
+    updateColumns();
+    query.addEventListener("change", updateColumns);
+    return () => query.removeEventListener("change", updateColumns);
+  }, []);
 
   const handleLoadError = (event: Parameters<
     NonNullable<React.ComponentProps<typeof PaymentElement>["onLoadError"]>
@@ -134,38 +191,118 @@ function StripePaymentForm({
     );
   };
 
-  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    if (!stripe || !elements || isSubmitting) return;
+  const updateExpressAvailability = (
+    availablePaymentMethods:
+      | AvailablePaymentMethods
+      | {
+          applePay?: { available: boolean };
+          googlePay?: { available: boolean };
+          link?: { available: boolean };
+          paypal?: { available: boolean };
+          amazonPay?: { available: boolean };
+          klarna?: { available: boolean };
+        }
+      | undefined,
+  ) => {
+    const availability = {
+      applePay: isExpressMethodAvailable(availablePaymentMethods?.applePay),
+      googlePay: isExpressMethodAvailable(availablePaymentMethods?.googlePay),
+      link: isExpressMethodAvailable(availablePaymentMethods?.link),
+      paypal: isExpressMethodAvailable(availablePaymentMethods?.paypal),
+      amazonPay: isExpressMethodAvailable(availablePaymentMethods?.amazonPay),
+      klarna: isExpressMethodAvailable(availablePaymentMethods?.klarna),
+    };
+    setHasExpressPaymentMethods(Object.values(availability).some(Boolean));
+    const browser = BrowserDetector.isFacebookInAppBrowser()
+        ? "facebook"
+        : BrowserDetector.getBrowserName() || "unknown";
+    const platform = PlatformDetector.getPlatform();
+    const metadata = {
+      browser,
+      platform,
+      availablePaymentMethods: availability,
+    };
+    log.info(
+      "[stripe-payment-dialog] Express Checkout availability",
+      metadata,
+    );
+    behaviorAnalytics.elementClick(
+      "stripe.express_checkout_availability",
+      "Stripe Express Checkout availability",
+      metadata,
+    );
+  };
 
+  const handleExpressLoadError = (event: Parameters<
+    NonNullable<
+      React.ComponentProps<typeof ExpressCheckoutElement>["onLoadError"]
+    >
+  >[0]) => {
+    setHasExpressPaymentMethods(false);
+    log.warn("[stripe-payment-dialog] Express Checkout load failed", {
+      type: event.error.type,
+      code: event.error.code,
+      message: event.error.message,
+    });
+  };
+
+  const confirmPayment = async (
+    options: {
+      submitPaymentElement: boolean;
+      expressEvent?: StripeExpressCheckoutElementConfirmEvent;
+    },
+  ) => {
+    if (!stripe || !elements || submittingRef.current) return;
+
+    submittingRef.current = true;
     setIsSubmitting(true);
     setErrorMessage(null);
 
-    const { error: submitError } = await elements.submit();
+    if (options.submitPaymentElement) {
+      let submitError: unknown;
+      try {
+        ({ error: submitError } = await elements.submit());
+      } catch (error) {
+        submitError = error;
+      }
       if (submitError) {
         setErrorMessage(
-        ExceptionHandler.message(submitError, "Please check your payment info."),
+          ExceptionHandler.message(
+            submitError,
+            "Please check your payment info.",
+          ),
         );
+        submittingRef.current = false;
         setIsSubmitting(false);
         return;
       }
+    }
 
     const returnUrl = new URL(
       returnPath ?? ROUTES.subscription + "/success",
       window.location.origin,
     );
-    const { error } = await stripe.confirmPayment({
+    let confirmationError: unknown;
+    try {
+      ({ error: confirmationError } = await stripe.confirmPayment({
         elements,
         confirmParams: {
           return_url: returnUrl.toString(),
         },
         redirect: "if_required",
-    });
+      }));
+    } catch (error) {
+      confirmationError = error;
+    }
 
-    if (error) {
-      setErrorMessage(
-        ExceptionHandler.message(error, "Payment confirmation failed."),
+    if (confirmationError) {
+      const message = ExceptionHandler.message(
+        confirmationError,
+        "Payment confirmation failed.",
       );
+      setErrorMessage(message);
+      options.expressEvent?.paymentFailed({ reason: "fail", message });
+      submittingRef.current = false;
       setIsSubmitting(false);
       return;
     }
@@ -173,9 +310,74 @@ function StripePaymentForm({
     onConfirmed?.();
   };
 
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    await confirmPayment({ submitPaymentElement: true });
+  };
+
   return (
     <form className={styles.form} onSubmit={handleSubmit}>
-      <PaymentElement onLoadError={handleLoadError} />
+      <section
+        className={styles.expressSection}
+        hidden={hasExpressPaymentMethods === false}
+        aria-label="Express payment methods"
+      >
+        <ExpressCheckoutElement
+          options={{
+            paymentMethodOrder: [
+              "apple_pay",
+              "google_pay",
+              "link",
+              "paypal",
+              "amazon_pay",
+              "klarna",
+            ],
+            paymentMethods: {
+              applePay: "always",
+              googlePay: "always",
+              link: "auto",
+              paypal: "auto",
+              amazonPay: "auto",
+              klarna: "auto",
+            },
+            layout: {
+              maxColumns: expressMaxColumns,
+              maxRows: 6,
+              overflow: "never",
+            },
+          }}
+          onReady={(event) =>
+            updateExpressAvailability(event.availablePaymentMethods)
+          }
+          onAvailablePaymentMethodsChange={(event) =>
+            updateExpressAvailability(event.paymentMethods)
+          }
+          onLoadError={handleExpressLoadError}
+          onConfirm={(event) =>
+            void confirmPayment({
+              submitPaymentElement: false,
+              expressEvent: event,
+            })
+          }
+        />
+      </section>
+      <section className={styles.cardSection} aria-labelledby="pay-by-card-title">
+        <h3 id="pay-by-card-title" className={styles.cardTitle}>
+          Pay by card
+        </h3>
+        <PaymentElement
+          options={{
+            layout: { type: "accordion", defaultCollapsed: true },
+            paymentMethodOrder: ["card"],
+            wallets: {
+              applePay: "never",
+              googlePay: "never",
+              link: "never",
+            },
+          }}
+          onLoadError={handleLoadError}
+        />
+      </section>
       {errorMessage ? (
         <p
           role="alert"

src/app/_components/user-message-avatar.tsx

@@ -2,19 +2,30 @@
 
 import Image from "next/image";
 
-export interface UserMessageAvatarProps {
+import type { AvatarInteractionProps } from "./avatar-interaction";
+
+interface UserMessageAvatarVisualProps {
   avatarUrl?: string | null;
   className?: string;
   size?: number | string;
 }
 
+export type UserMessageAvatarProps = UserMessageAvatarVisualProps &
+  AvatarInteractionProps;
+
 export function UserMessageAvatar({
   avatarUrl,
   className,
   size = 43,
+  onClick,
+  actionLabel,
+  analyticsKey,
 }: UserMessageAvatarProps) {
   const avatarClassName = [
     "flex shrink-0 items-center justify-center overflow-hidden rounded-full border-2 border-(--color-avatar-border,#fbf3f5) bg-(--color-avatar-border,#fbf3f5) shadow-(--shadow-input-box,0_1px_2px_rgba(0,0,0,0.1))",
+    onClick
+      ? "cursor-pointer p-0 transition-transform duration-150 focus-visible:outline-3 focus-visible:outline-offset-3 focus-visible:outline-accent active:scale-96"
+      : undefined,
     className,
   ]
     .filter(Boolean)
@@ -22,21 +33,30 @@ export function UserMessageAvatar({
   const avatarStyle = { width: size, height: size };
   const imageSize = typeof size === "number" ? size : 64;
 
-  if (avatarUrl && avatarUrl.length > 0) {
-    return (
-      <div
-        className={avatarClassName}
-        style={avatarStyle}
-        aria-label="User avatar"
-      >
+  const hasUserAvatar = Boolean(avatarUrl && avatarUrl.length > 0);
+  const image = (
     <Image
-          src={avatarUrl}
-          alt=""
+      src={hasUserAvatar ? avatarUrl! : "/images/avatar/placeholder.png"}
+      alt={hasUserAvatar ? "" : "Guest"}
       width={imageSize}
       height={imageSize}
       className="size-full object-cover"
     />
-      </div>
+  );
+
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        className={avatarClassName}
+        style={avatarStyle}
+        aria-label={actionLabel}
+        data-analytics-key={analyticsKey}
+        data-analytics-label={actionLabel}
+        onClick={onClick}
+      >
+        {image}
+      </button>
     );
   }
 
@@ -44,15 +64,9 @@ export function UserMessageAvatar({
     <div
       className={avatarClassName}
       style={avatarStyle}
-      aria-label="Guest avatar"
+      aria-label={hasUserAvatar ? "User avatar" : "Guest avatar"}
     >
-      <Image
-        src="/images/avatar/placeholder.png"
-        alt="Guest"
-        width={imageSize}
-        height={imageSize}
-        className="size-full object-cover"
-      />
+      {image}
     </div>
   );
 }

src/app/_hooks/use-payment-launch-flow.ts

@@ -4,9 +4,12 @@ import { type Dispatch, useEffect, useRef, useState } from "react";
 
 import {
   getPaymentUrl,
+  getPaymentUrlHostname,
+  getStripeCustomerSessionClientSecret,
   getStripeClientSecret,
   isEzpayPayment,
   launchEzpayRedirect,
+  resolveEzpayLaunchTarget,
 } from "@/lib/payment/payment_launch";
 import { behaviorAnalytics } from "@/lib/analytics";
 import type {
@@ -40,19 +43,63 @@ export interface UsePaymentLaunchFlowInput {
   subscriptionType: PendingPaymentSubscriptionType;
   giftCategory?: string | null;
   giftPlanId?: string | null;
+  countryCode?: string | null;
 }
 
 export interface PaymentLaunchFlow {
   ezpayPaymentUrl: string | null;
   handleEzpayCancel: () => void;
   handleEzpayConfirm: () => void;
+  handleRegionalQrClose: () => void;
   handleStripeClose: () => void;
   handleStripeConfirmed: () => void;
   isConfirmingEzpay: boolean;
+  regionalQrErrorMessage: string | null;
+  regionalQrPayment: RegionalQrPaymentDetails | null;
+  regionalQrStatus: PaymentContextState["orderStatus"];
   resetLaunchState: () => void;
   shouldShowEzpayConfirmDialog: boolean;
+  shouldShowRegionalQrDialog: boolean;
   shouldShowStripeDialog: boolean;
   stripeClientSecret: string | null;
+  stripeCustomerSessionClientSecret: string | null;
+  savedPaymentMethodsEnabled: boolean;
+}
+
+export interface RegionalQrPaymentDetails {
+  amountCents: number;
+  currency: string;
+  experience: "gcashQrPh" | "qris" | "paymentQr";
+  orderId: string;
+  qrData: string;
+}
+
+function paymentParamString(
+  payParams: Record<string, unknown>,
+  ...keys: string[]
+): string | null {
+  for (const key of keys) {
+    const value = payParams[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function paymentParamAmountCents(
+  payParams: Record<string, unknown>,
+): number | null {
+  for (const key of [
+    "firstChargeAmountCents",
+    "first_charge_amount_cents",
+    "amountCents",
+    "amount_cents",
+  ]) {
+    const value = payParams[key];
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+      return value;
+    }
+  }
+  return null;
 }
 
 function trackPaymentCheckoutOpened(
@@ -112,6 +159,7 @@ export function usePaymentLaunchFlow({
   subscriptionType,
   giftCategory,
   giftPlanId,
+  countryCode,
 }: UsePaymentLaunchFlowInput): PaymentLaunchFlow {
   const launchedNonceRef = useRef(0);
   const [hiddenStripeClientSecret, setHiddenStripeClientSecret] = useState<
@@ -121,8 +169,44 @@ export function usePaymentLaunchFlow({
   const stripeClientSecret = payment.payParams
     ? getStripeClientSecret(payment.payParams)
     : null;
-  const ezpayPaymentUrl = payment.payParams
-    ? getPaymentUrl(payment.payParams)
+  const stripeCustomerSessionClientSecret = payment.payParams
+    ? getStripeCustomerSessionClientSecret(payment.payParams)
+    : null;
+  const selectedPlan = payment.plans.find(
+    (item) => item.planId === payment.selectedPlanId,
+  );
+  const paymentCurrency = payment.payParams
+    ? paymentParamString(payment.payParams, "currency") ??
+      selectedPlan?.currency ??
+      null
+    : selectedPlan?.currency ?? null;
+  const ezpayLaunchTarget =
+    payment.payParams && isEzpayPayment(payment.payParams)
+      ? resolveEzpayLaunchTarget(payment.payParams, {
+          countryCode,
+          currency: paymentCurrency,
+        })
+      : null;
+  const ezpayPaymentUrl =
+    ezpayLaunchTarget?.kind === "url"
+      ? ezpayLaunchTarget.paymentUrl
+      : null;
+  const regionalQrPayment: RegionalQrPaymentDetails | null =
+    payment.payParams &&
+    payment.currentOrderId &&
+    ezpayLaunchTarget?.kind === "qr"
+      ? {
+          amountCents:
+            paymentParamAmountCents(payment.payParams) ??
+            selectedPlan?.amountCents ??
+            0,
+          currency:
+            paymentCurrency ??
+            (ezpayLaunchTarget.experience === "gcashQrPh" ? "PHP" : "IDR"),
+          experience: ezpayLaunchTarget.experience,
+          orderId: payment.currentOrderId,
+          qrData: ezpayLaunchTarget.qrData,
+        }
       : null;
   useEffect(() => {
     if (!payment.payParams || payment.launchNonce <= launchedNonceRef.current) {
@@ -136,20 +220,74 @@ export function usePaymentLaunchFlow({
       return;
     }
 
-    const paymentUrl = getPaymentUrl(payment.payParams);
-    if (paymentUrl) {
     const isEzpay = isEzpayPayment(payment.payParams);
+    if (isEzpay) {
+      const target = resolveEzpayLaunchTarget(payment.payParams, {
+        countryCode,
+        currency: paymentCurrency,
+      });
+      const channelType = paymentParamString(
+        payment.payParams,
+        "channelType",
+        "channel_type",
+      );
+      const channelCode = paymentParamString(
+        payment.payParams,
+        "channelCode",
+        "channel_code",
+      );
+      const namedPaymentUrl = getPaymentUrl(payment.payParams);
+      log.debug(`[${logScope}] ezpay launch target resolved`, {
+        countryCode: countryCode?.trim().toUpperCase() ?? null,
+        currency: paymentCurrency?.trim().toUpperCase() ?? null,
+        channelType: channelType?.toUpperCase() ?? null,
+        channelCode,
+        hasCashierUrl: getPaymentUrlHostname(namedPaymentUrl) !== null,
+        hasQrData: target.kind === "qr",
+        paymentUrlHost:
+          target.kind === "url"
+            ? getPaymentUrlHostname(target.paymentUrl)
+            : null,
+      });
+      if (target.kind === "error") {
+        trackPaymentCheckoutFailed(payment, "missing_checkout_url");
+        paymentDispatch({
+          type: "PaymentLaunchFailed",
+          errorMessage: target.errorMessage,
+        });
+        return;
+      }
 
-      if (!AppEnvUtil.isProduction() && isEzpay) {
+      if (target.kind === "qr") {
+        if (!payment.currentOrderId) {
+          trackPaymentCheckoutFailed(payment, "missing_checkout_url");
+          paymentDispatch({
+            type: "PaymentLaunchFailed",
+            errorMessage: "Missing order id before showing payment QR code.",
+          });
+          return;
+        }
+        trackPaymentCheckoutOpened(
+          payment,
+          target.experience === "qris"
+            ? "qris_embedded"
+            : target.experience === "gcashQrPh"
+              ? "gcash_qrph_embedded"
+              : "payment_qr_embedded",
+        );
+        return;
+      }
+
+      const paymentUrl = target.paymentUrl;
+      if (!AppEnvUtil.isProduction()) {
         log.debug(`[${logScope}] ezpay confirmation required`, {
           orderId: payment.currentOrderId,
-          paymentUrl,
+          paymentUrlHost: getPaymentUrlHostname(paymentUrl),
           subscriptionType,
         });
         return;
       }
 
-      if (isEzpay) {
       void launchEzpayRedirect({
         orderId: payment.currentOrderId,
         paymentUrl,
@@ -167,8 +305,10 @@ export function usePaymentLaunchFlow({
       return;
     }
 
+    const paymentUrl = getPaymentUrl(payment.payParams);
+    if (paymentUrl) {
       try {
-        window.location.href = paymentUrl;
+        window.location.assign(paymentUrl);
         trackPaymentCheckoutOpened(payment, paymentUrl);
       } catch {
         trackPaymentCheckoutFailed(payment, "payment_redirect_failed");
@@ -189,6 +329,7 @@ export function usePaymentLaunchFlow({
     log,
     logScope,
     characterSlug,
+    countryCode,
     payment.currentOrderId,
     payment,
     payment.launchNonce,
@@ -197,6 +338,7 @@ export function usePaymentLaunchFlow({
     payment.plans,
     payment.selectedPlanId,
     paymentDispatch,
+    paymentCurrency,
     returnTo,
     subscriptionType,
     giftCategory,
@@ -213,6 +355,9 @@ export function usePaymentLaunchFlow({
     payParams: payment.payParams,
     paymentUrl: ezpayPaymentUrl,
   });
+  const shouldShowRegionalQrDialog = Boolean(
+    regionalQrPayment && !payment.isPaid,
+  );
 
   function resetLaunchState(): void {
     setIsConfirmingEzpay(false);
@@ -263,16 +408,33 @@ export function usePaymentLaunchFlow({
     paymentDispatch({ type: "PaymentReset" });
   }
 
+  function handleRegionalQrClose(): void {
+    log.debug(`[${logScope}] regional payment QR dialog closed`, {
+      orderId: regionalQrPayment?.orderId ?? payment.currentOrderId,
+      experience: regionalQrPayment?.experience ?? null,
+      subscriptionType,
+    });
+    paymentDispatch({ type: "PaymentReset" });
+  }
+
   return {
     ezpayPaymentUrl,
     handleEzpayCancel,
     handleEzpayConfirm,
+    handleRegionalQrClose,
     handleStripeClose,
     handleStripeConfirmed,
     isConfirmingEzpay,
+    regionalQrErrorMessage: payment.errorMessage,
+    regionalQrPayment,
+    regionalQrStatus: payment.orderStatus,
     resetLaunchState,
     shouldShowEzpayConfirmDialog,
+    shouldShowRegionalQrDialog,
     shouldShowStripeDialog,
     stripeClientSecret,
+    stripeCustomerSessionClientSecret,
+    savedPaymentMethodsEnabled:
+      stripeCustomerSessionClientSecret !== null,
   };
 }