fix(payment): route Philippine GCash separately from QRIS

.gitea/workflows/docker-image.yml

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

.gitea/workflows/domestic-test.yml

@@ -0,0 +1,138 @@
+name: Deploy frontend to domestic test
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Build and deploy isolated domestic test
+    runs-on: gitea-label
+    container:
+      image: cozsweet-act-runner-node24-docker:latest
+    env:
+      NEXT_TELEMETRY_DISABLED: "1"
+      SENTRY_UPLOAD_SOURCEMAPS: "0"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate domestic SSH configuration
+        env:
+          SSH_HOST: ${{ secrets.DOMESTIC_TEST_SSH_HOST }}
+          SSH_PORT: ${{ secrets.DOMESTIC_TEST_SSH_PORT }}
+          SSH_PRIVATE_KEY_B64: ${{ secrets.DOMESTIC_TEST_SSH_PRIVATE_KEY_B64 }}
+          SSH_KNOWN_HOSTS: ${{ secrets.DOMESTIC_TEST_SSH_KNOWN_HOSTS }}
+        run: |
+          set -eu
+          if [ -z "$SSH_HOST" ] || [ -z "$SSH_PRIVATE_KEY_B64" ] || [ -z "$SSH_KNOWN_HOSTS" ]; then
+            echo "Missing domestic test SSH secrets" >&2
+            exit 1
+          fi
+          mkdir -p "$HOME/.ssh"
+          chmod 700 "$HOME/.ssh"
+          printf '%s' "$SSH_PRIVATE_KEY_B64" | base64 -d > "$HOME/.ssh/domestic_test_deploy_key"
+          printf '%s\n' "$SSH_KNOWN_HOSTS" > "$HOME/.ssh/known_hosts"
+          chmod 600 "$HOME/.ssh/domestic_test_deploy_key" "$HOME/.ssh/known_hosts"
+
+      - name: Prepare domestic test environment
+        env:
+          TEST_ENV_FILE_CONTENT: ${{ secrets.TEST_ENV_FILE }}
+        run: |
+          set -eu
+          if [ -z "$TEST_ENV_FILE_CONTENT" ]; then
+            echo "Missing existing secret: TEST_ENV_FILE" >&2
+            exit 1
+          fi
+          umask 077
+          printf '%s\n' "$TEST_ENV_FILE_CONTENT" > .env.domestic-test
+
+          replace_env() {
+            key="$1"
+            value="$2"
+            awk -v key="$key" -v value="$value" '
+              BEGIN { replaced = 0 }
+              $0 ~ "^" key "=" { print key "=" value; replaced = 1; next }
+              { print }
+              END { if (!replaced) print key "=" value }
+            ' .env.domestic-test > .env.domestic-test.next
+            mv .env.domestic-test.next .env.domestic-test
+          }
+
+          replace_env NEXT_PUBLIC_APP_ENV test
+          replace_env NEXT_PUBLIC_API_BASE_URL https://testapi.banlv-ai.com
+          replace_env NEXT_PUBLIC_WS_BASE_URL wss://testapi.banlv-ai.com/ws
+          replace_env NEXTAUTH_URL http://127.0.0.1:9135
+          replace_env NEXTAUTH_URL_INTERNAL http://127.0.0.1:3000
+
+          grep -Eq '^AUTH_SECRET=.+$' .env.domestic-test
+          grep -Eq '^NEXT_PUBLIC_API_BASE_URL=https://testapi\.banlv-ai\.com/?$' .env.domestic-test
+          grep -Eq '^NEXT_PUBLIC_WS_BASE_URL=wss://testapi\.banlv-ai\.com/ws/?$' .env.domestic-test
+
+      - name: Prepare image metadata
+        run: |
+          set -eu
+          SHORT_SHA="$(git rev-parse --short HEAD)"
+          IMAGE="cozsweet-frontend-domestic-test:test-$SHORT_SHA"
+          ARCHIVE="cozsweet-frontend-domestic-test-$SHORT_SHA.tar.gz"
+          {
+            echo "SHORT_SHA=$SHORT_SHA"
+            echo "IMAGE=$IMAGE"
+            echo "ARCHIVE=$ARCHIVE"
+          } >> "$GITHUB_ENV"
+
+      - name: Run frontend quality checks
+        run: |
+          set -eu
+          pnpm install --frozen-lockfile
+          pnpm lint
+          pnpm typecheck
+          pnpm test:contracts
+
+      - name: Build and archive runtime image
+        run: |
+          set -eu
+          DOCKER_BUILDKIT=1 docker build \
+            --secret id=next_env,src=.env.domestic-test \
+            --build-arg NEXT_ENV_FILE=.env.domestic-test \
+            -t "$IMAGE" \
+            .
+          docker save "$IMAGE" | gzip -1 > "$ARCHIVE"
+          test -s "$ARCHIVE"
+
+      - name: Deploy isolated domestic test container
+        env:
+          SSH_HOST: ${{ secrets.DOMESTIC_TEST_SSH_HOST }}
+          SSH_PORT: ${{ secrets.DOMESTIC_TEST_SSH_PORT }}
+        run: |
+          set -eu
+          DEPLOY_PORT="${SSH_PORT:-22}"
+          KEY_FILE="$HOME/.ssh/domestic_test_deploy_key"
+          SSH_TARGET="lzf@$SSH_HOST"
+          RUN_TOKEN="${GITHUB_RUN_ID:-manual}-${GITHUB_RUN_ATTEMPT:-1}"
+          DEPLOY_ROOT="/home/lzf/apps/cozsweet-web-test"
+          REMOTE_TMP="$DEPLOY_ROOT/tmp/actions-$RUN_TOKEN"
+          REMOTE_ARCHIVE="$REMOTE_TMP/$ARCHIVE"
+          REMOTE_ENV_FILE="$DEPLOY_ROOT/shared/test.env"
+          SSH_OPTS="-i $KEY_FILE -p $DEPLOY_PORT -o BatchMode=yes -o IdentitiesOnly=yes"
+          SCP_OPTS="-i $KEY_FILE -P $DEPLOY_PORT -o BatchMode=yes -o IdentitiesOnly=yes"
+
+          cleanup_remote() {
+            ssh $SSH_OPTS "$SSH_TARGET" \
+              "rm -f '$REMOTE_ARCHIVE' && rmdir '$REMOTE_TMP' 2>/dev/null || true"
+          }
+          trap cleanup_remote EXIT
+
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "mkdir -p '$DEPLOY_ROOT/current' '$DEPLOY_ROOT/releases/docker' '$DEPLOY_ROOT/shared' '$REMOTE_TMP' && chmod 700 '$DEPLOY_ROOT/shared'"
+          scp $SCP_OPTS scripts/server/deploy-domestic-test-archive.sh \
+            "$SSH_TARGET:$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh"
+          scp $SCP_OPTS .env.domestic-test "$SSH_TARGET:$REMOTE_ENV_FILE"
+          scp $SCP_OPTS "$ARCHIVE" "$SSH_TARGET:$REMOTE_ARCHIVE"
+          ssh $SSH_OPTS "$SSH_TARGET" \
+            "chmod 600 '$REMOTE_ENV_FILE' && chmod 700 '$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh' && '$DEPLOY_ROOT/current/deploy-domestic-test-archive.sh' '$REMOTE_ARCHIVE' '$IMAGE' '$REMOTE_ENV_FILE' 9135"
+
+      - name: Cleanup runner artifacts
+        if: always()
+        run: |
+          rm -f .env.domestic-test .env.domestic-test.next "${ARCHIVE:-}" "$HOME/.ssh/domestic_test_deploy_key"

.githooks/post-receive

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

docs/auto-build-restart.md

@@ -12,7 +12,7 @@
 
 | 环境 | Git remote | 推送分支 | 宿主机端口 | 容器端口 | 部署脚本 |
 | --- | --- | --- | --- | --- | --- |
-| 预发环境 | `test` | `pre` | `9135` | `3000` | `scripts/deploy/deploy_web_test.sh` |
+| 测试环境 | `test` | `test` | `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. 进入 pre worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-pre`
+1. 进入 test worktree：`cozsweet-frontend-nextjs.worktrees/cozsweet-nextjs-test`
 2. 确认当前分支。
-3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `pre` 分支。
+3. 执行 `git rebase dev`，把 `dev` 的最新代码变基到 `test` 分支。
 4. 复制测试环境图标到 `public/`。
 5. 复制 `env-example/.env.local.example` 到 `.env.local`。
 6. 执行旧版 `scripts/deploy/deploy_web_test.sh`。
-7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `pre` 分支。
+7. 旧版 `deploy_web_test.sh` 推送 `test` remote 的 `test` 分支。
 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>` |
-| `pre` | `env-example/.env.local.example` → `.env.local` | `9135` | `cozsweet-web-test` | `cozsweet-web:test-<commit>` |
+| `test` | `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` 分支对应生产环境，`pre` 分支对应预发环境。
+3. `main` 分支对应生产环境，`test` 分支对应测试环境。
 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/docker-image-ci.md

@@ -8,13 +8,13 @@
 
 | Workflow | 触发时机 | 职责 |
 | --- | --- | --- |
-| `.gitea/workflows/ci.yml` | `dev`、`main`、`pre` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
+| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
-| `.gitea/workflows/docker-image.yml` | `main`、`pre` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
+| `.gitea/workflows/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
 
 这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。
 
-`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`pre`
+`main` 分支发布前会执行 Docker workflow 内的完整质量和 bundle 门禁。`test`
-分支用于快速部署预发环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
+分支为快速部署测试环境，会跳过完整质量检查，但仍必须通过 bundle 预算；独立的
 `ci.yml` 会同时执行完整检查并提供测试结果。
 
 ## 必需 Secrets
@@ -39,7 +39,7 @@ Next.js 的 `NEXT_PUBLIC_*` 会在构建期固化到产物中，因此测试环
 
 ## 镜像 Tag 规则
 
-`pre` 分支发布时继续使用现有 `test-*` 运行镜像标签：
+`test` 分支发布：
 
 ```bash
 REGISTRY_IMAGE:test-<short_sha>
@@ -81,7 +81,7 @@ volumes:
 
 ## 验证方式
 
-推送到 `pre` 分支后，检查 Actions 日志中是否出现：
+推送到 `test` 分支后，检查 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

@@ -1,11 +1,11 @@
 # 外部入口接入说明
 
-外部应用通过 `/external-entry` 进入本应用。
+Facebook 等外部应用统一通过 `/external-entry` 进入本应用。入口先保存外部身份和短期业务意图，再跳转到对应角色页面并清理地址栏中的入口查询参数。
 
 | 环境 | APP HOST |
 | --- | --- |
-| 测试环境 | `frontend-test.banlv-ai.com` |
+| 预发环境 `pre` | `frontend-test.banlv-ai.com` |
-| 正式环境 | `cozsweet.com` |
+| 正式环境 `production` | `cozsweet.com` |
 
 入口格式：
 
@@ -13,85 +13,78 @@
 https://<APP_HOST>/external-entry?<参数>
 ```
 
-## 可选参数
+## 当前 Facebook 业务入口
 
-所有参数均为可选参数。
+当前正式投放固定为 4 类入口乘以 3 个角色，共 12 条链接。Facebook 业务名称与应用页面的对应关系如下：
+
+| Facebook 入口 | 参数组合 | 落地行为 |
+| --- | --- | --- |
+| 私密空间 | `target=chat` | 进入普通聊天页，不插入任何锁定内容。 |
+| 语音 | `target=chat&mode=promotion&promotion_type=voice` | 进入聊天页，并插入一条待解锁语音。 |
+| 图片包 | `target=private-zone` | 进入角色的 `private-zone` 图片空间。 |
+| 帮忙买咖啡 | `target=tip` | 进入角色的咖啡打赏页。 |
+
+每条正式链接还必须显式传入：
+
+- `character=elio`、`character=maya` 或 `character=nayeli`；
+- `psid=<PSID>`，其中 `<PSID>` 必须由 Facebook 发送端替换为当前用户经过 URL 编码的 Page-scoped User ID。
+
+完整的 12 条正式发送模板见 [Facebook 12 条外部入口链接清单](./links.md)。
+
+## 参数说明
 
 | 参数 | 可选值或格式 | 用途 |
 | --- | --- | --- |
-| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。历史值 `private-room` 兼容进入 `private-zone`，新链接不得继续使用。 |
+| `target` | `chat`、`tip`、`private-zone` | 指定进入的页面；不传或值无效时进入聊天页。 |
-| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。 |
+| `character` | `elio`、`maya`、`nayeli` | 指定角色；不传或值无效时使用 Elio。正式投放链接必须显式传入。 |
-| `psid` | string | 传入 Facebook Page-scoped User ID。 |
+| `psid` | string | Facebook Page-scoped User ID。Facebook 正式投放链接必须动态传入。 |
 | `mode` | `promotion` | 开启聊天促销模式。 |
 | `promotion_type` | `voice`、`image`、`private` | 指定促销消息类型，仅与 `mode=promotion` 一起使用。 |
 
-`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。
+`mode=promotion` 只有在 `target=chat` 且同时提供有效的 `promotion_type` 时生效。当前 12 条正式投放链接只使用 `promotion_type=voice`；`image` 和 `private` 保留为兼容能力，不属于本次业务清单。
 
-标准私密空间参数是 `target=private-zone`。前端仅为已经发布的旧链接保留 `target=private-room` 兼容；`private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
+## 四类发送模板
+
+发送前必须把 `<CHARACTER>` 替换为角色值，把 `<PSID>` 替换为当前 Facebook 用户的真实 PSID；不得把占位符原样发送给用户。
+
+私密空间（普通聊天）：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&psid=<PSID>
+```
+
+语音：
+
+```text
+https://<APP_HOST>/external-entry?target=chat&character=<CHARACTER>&mode=promotion&promotion_type=voice&psid=<PSID>
+```
+
+图片包：
+
+```text
+https://<APP_HOST>/external-entry?target=private-zone&character=<CHARACTER>&psid=<PSID>
+```
+
+帮忙买咖啡：
+
+```text
+https://<APP_HOST>/external-entry?target=tip&character=<CHARACTER>&psid=<PSID>
+```
 
 ## PSID 与登录状态流程
 
-PSID 保存、登录状态判断和 Facebook Identity 绑定逻辑见 [PSID 与登录状态流程图](./psid-login-flow.md)。
+`psid` 可以和任意有效入口参数组合使用。应用会先保存 PSID，再执行登录状态判断和 Facebook Identity 绑定。详细流程见 [PSID 与登录状态流程图](./psid-login-flow.md)。
 
-## 使用示例
+所有参数值都必须进行 URL 编码。入口中禁止传递登录 Token、Page Access Token、App Secret 或其他秘密。
 
-普通聊天：
+## 兼容说明
 
-```text
+- 历史参数 `target=private-room` 继续兼容进入 `private-zone`，但不得用于新投放链接。
-https://<APP_HOST>/external-entry?target=chat
+- `private_zone` 等其他拼写仍按无效目标处理并回退聊天页。
-```
+- `promotion_type=image` 和 `promotion_type=private` 继续由现有代码支持，但不计入当前 12 条 Facebook 业务链接。
+- 无效或缺失的 `character` 继续回退 Elio；正式投放模板始终显式传入角色，不能依赖回退。
 
-进入 Maya 聊天：
+## 调试与正式清单
-
-```text
-https://<APP_HOST>/external-entry?target=chat&character=maya
-```
-
-携带 PSID 进入聊天，示例 PSID 为 `27511427698460020`：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&psid=27511427698460020
-```
-
-语音促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=voice
-```
-
-图片促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=image
-```
-
-私密文本促销聊天：
-
-```text
-https://<APP_HOST>/external-entry?target=chat&mode=promotion&promotion_type=private
-```
-
-咖啡打赏：
-
-```text
-https://<APP_HOST>/external-entry?target=tip
-```
-
-私密空间：
-
-```text
-https://<APP_HOST>/external-entry?target=private-zone
-```
-
-进入 Nayeli 私密空间：
-
-```text
-https://<APP_HOST>/external-entry?target=private-zone&character=nayeli
-```
-
-`psid` 可以与任意 `target` 或聊天促销参数组合使用。参数值需要进行 URL 编码，不要在入口中传递登录 Token、Page Access Token 或 App Secret。
-
-完整可点击示例：
 
 - [本地调试链接清单](./debug-links.md)
-- [测试环境和正式环境链接清单](./links.md)
+- [Facebook 12 条外部入口链接清单](./links.md)

docs/external-entry/links.md

@@ -1,66 +1,52 @@
-# 外部入口链接清单
+# Facebook 12 条外部入口链接清单
 
-这份清单可以独立发送和直接点击。所有新链接统一使用标准参数 `target=private-zone`；历史参数 `target=private-room` 仅用于兼容已经发出的旧链接。
+本清单是 Facebook 正式投放的唯一业务链接清单，共 4 类入口乘以 3 个角色，合计 12 条模板。
 
-## 使用规则
+## 发送规则
 
-- `target=chat`：进入聊天页。
+- 发送前必须把每条模板中的 `<PSID>` 替换为当前用户经过 URL 编码的 Facebook Page-scoped User ID；不得把占位符原样发送。
-- `target=tip`：进入对应角色的打赏页。
+- 每条链接都显式传入 `character`，不得依赖缺省角色回退。
-- `target=private-zone`：进入对应角色的私密空间。
+- Facebook 业务名称“私密空间”进入普通聊天页；业务名称“图片包”才进入应用的 `private-zone`。
-- `character` 可使用 `elio`、`maya`、`nayeli`；不传或值无效时使用 Elio。
+- 不要在入口中传递登录 Token、Page Access Token、App Secret 或其他秘密。
-- `mode=promotion` 只在 `target=chat` 且 `promotion_type` 为 `voice`、`image` 或 `private` 时生效。
+- 以下模板包含占位符，替换真实 PSID 后才能直接发送或点击。
-- PSID 示例统一使用 `27511427698460020`；不要在入口中放登录 Token、Page Access Token 或 App Secret。
 
-## 测试环境
+## 正式投放模板
 
-| 入口 | 可点击链接 | 预期落地页面 |
+| 编号 | Facebook 入口 | 角色 | 发送模板 | 预期落地与页面状态 |
-| --- | --- | --- |
+| --- | --- | --- | --- | --- |
-| 普通聊天（Elio） | [打开普通聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat) | `/characters/elio/chat` |
+| 1 | 私密空间 | Elio | `https://cozsweet.com/external-entry?target=chat&character=elio&psid=<PSID>` | `/characters/elio/chat`，不显示促销锁卡 |
-| Maya 聊天 | [打开 Maya 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=maya) | `/characters/maya/chat` |
+| 2 | 私密空间 | Maya | `https://cozsweet.com/external-entry?target=chat&character=maya&psid=<PSID>` | `/characters/maya/chat`，不显示促销锁卡 |
-| Nayeli 聊天 | [打开 Nayeli 聊天](https://frontend-test.banlv-ai.com/external-entry?target=chat&character=nayeli) | `/characters/nayeli/chat` |
+| 3 | 私密空间 | Nayeli | `https://cozsweet.com/external-entry?target=chat&character=nayeli&psid=<PSID>` | `/characters/nayeli/chat`，不显示促销锁卡 |
-| 携带 PSID 的 Elio 聊天 | [打开 PSID 聊天示例](https://frontend-test.banlv-ai.com/external-entry?target=chat&psid=27511427698460020) | `/characters/elio/chat` |
+| 4 | 语音 | Elio | `https://cozsweet.com/external-entry?target=chat&character=elio&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/elio/chat`，显示一条锁定语音 |
-| 语音促销 | [打开语音促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=voice) | `/characters/elio/chat`，保存语音促销意图 |
+| 5 | 语音 | Maya | `https://cozsweet.com/external-entry?target=chat&character=maya&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/maya/chat`，显示一条锁定语音 |
-| 图片促销 | [打开图片促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=image) | `/characters/elio/chat`，保存图片促销意图 |
+| 6 | 语音 | Nayeli | `https://cozsweet.com/external-entry?target=chat&character=nayeli&mode=promotion&promotion_type=voice&psid=<PSID>` | `/characters/nayeli/chat`，显示一条锁定语音 |
-| 私密文本促销 | [打开私密文本促销](https://frontend-test.banlv-ai.com/external-entry?target=chat&mode=promotion&promotion_type=private) | `/characters/elio/chat`，保存私密文本促销意图 |
+| 7 | 图片包 | Elio | `https://cozsweet.com/external-entry?target=private-zone&character=elio&psid=<PSID>` | `/characters/elio/private-zone` |
-| Elio 咖啡打赏 | [打开 Elio 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=elio) | `/characters/elio/tip` |
+| 8 | 图片包 | Maya | `https://cozsweet.com/external-entry?target=private-zone&character=maya&psid=<PSID>` | `/characters/maya/private-zone` |
-| Maya 咖啡打赏 | [打开 Maya 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=maya) | `/characters/maya/tip` |
+| 9 | 图片包 | Nayeli | `https://cozsweet.com/external-entry?target=private-zone&character=nayeli&psid=<PSID>` | `/characters/nayeli/private-zone` |
-| Nayeli 咖啡打赏 | [打开 Nayeli 咖啡打赏](https://frontend-test.banlv-ai.com/external-entry?target=tip&character=nayeli) | `/characters/nayeli/tip` |
+| 10 | 帮忙买咖啡 | Elio | `https://cozsweet.com/external-entry?target=tip&character=elio&psid=<PSID>` | `/characters/elio/tip` |
-| Elio 私密空间 | [打开 Elio 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=elio) | `/characters/elio/private-zone` |
+| 11 | 帮忙买咖啡 | Maya | `https://cozsweet.com/external-entry?target=tip&character=maya&psid=<PSID>` | `/characters/maya/tip` |
-| Maya 私密空间 | [打开 Maya 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=maya) | `/characters/maya/private-zone` |
+| 12 | 帮忙买咖啡 | Nayeli | `https://cozsweet.com/external-entry?target=tip&character=nayeli&psid=<PSID>` | `/characters/nayeli/tip` |
-| Nayeli 私密空间 | [打开 Nayeli 私密空间](https://frontend-test.banlv-ai.com/external-entry?target=private-zone&character=nayeli) | `/characters/nayeli/private-zone` |
 
-## 旧链接兼容验证
+## 预发验证
 
-以下链接仅用于验证已经发出的 `private-room` 旧链接仍能正确进入私密空间。新投放链接不要再使用这些地址。
+预发验证不维护第二套业务清单。将上述 12 条模板的主机统一替换为 `frontend-test.banlv-ai.com`，其余路径和参数保持不变：
 
-| 旧入口 | 可点击链接 | 预期落地页面 |
+```text
-| --- | --- | --- |
+https://frontend-test.banlv-ai.com/external-entry?<与正式模板相同的查询参数>
-| 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` |
 
-## 正式环境
+预发环境是 `pre`，不是正式环境。预发验证通过不代表已经更新 `cozsweet.com` 或获得生产发布批准。
-
-正式环境仅列标准链接，不再传播 `private-room` 旧参数。
-
-| 入口 | 可点击链接 | 预期落地页面 |
-| --- | --- | --- |
-| 普通聊天（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`，不能再进入同一个页面。
+- 最终浏览器地址必须是表格中的预期页面，且不再保留 `/external-entry` 的查询参数。
+- `<PSID>` 替换后的真实值必须由应用保存。
+- “私密空间”只进入普通聊天，不得出现锁定语音、锁定图片或私密文本促销卡。
+- “语音”进入聊天后必须只注入一条锁定语音。
+- “图片包”和“帮忙买咖啡”必须分别进入对应角色的 `private-zone` 与 `tip`，不能串到其他角色。
 
-如需在其他入口携带 PSID，在已有查询参数的链接末尾追加 `&psid=27511427698460020`。
+## 不属于当前 12 条清单的兼容能力
+
+- 历史 `target=private-room` 继续兼容，但不得创建新的投放链接。
+- `promotion_type=image`、`promotion_type=private` 和独立 PSID 示例不属于当前正式业务清单。
+- 兼容能力的保留不改变本页“只有 12 条正式投放模板”的口径。

docs/gitea-actions-ssh-deploy.md

@@ -3,7 +3,7 @@
 当前推荐部署链路：
 
 ```text
-push pre/main
+push test/main
 → Gitea Actions 构建并推送 Docker 镜像
 → Actions 通过 SSH 登录目标服务器
 → 目标服务器 docker pull 指定镜像 tag
@@ -16,7 +16,7 @@ push pre/main
 
 | 分支 | 环境 | 镜像 tag | 宿主机端口 | 默认服务器目录 | 容器名 |
 | --- | --- | --- | --- | --- | --- |
-| `pre` | 预发环境 | `test-<short_sha>` | `9135` | `/opt/cozsweet-web-test` | `cozsweet-web-test` |
+| `test` | 测试环境 | `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 pre
+git push gitea test
 git push --force gitea main
 ```
 
 ## 验证
 
-预发环境：
+测试环境：
 
 ```bash
-ssh <user>@<pre-host>
+ssh <user>@<test-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 在所有 pull
+refresh and paid-image unlock paths with the Pixel 7 profile. CI runs this tier
-request 以及 `dev` / `pre` / `main` push 时运行这一层测试。
+on every pull request and `dev` / `test` / `main` push.
 
 ## Environment overrides
 

e2e/fixtures/api-mocks.ts

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

e2e/fixtures/api/auth.ts

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

e2e/fixtures/data/auth.ts

@@ -50,14 +50,16 @@ export const refreshedEmailLoginResponse = {
   refreshToken: "e2e-refreshed-email-refresh-token",
 };
 
-export const psidLoginResponse = {
+export const topUpHandoffResponse = {
-  token: "e2e-psid-guest-token",
+  token: "e2e-messenger-token",
-  refreshToken: "",
+  refreshToken: "e2e-messenger-refresh-token",
-  matchedBy: "psid",
+  loginStatus: "facebookMessenger",
-  fbAsid: "",
+  merged: false,
-  fbPsid: "e2e-facebook-psid",
+  user: {
-  hasCompleteFacebookIdentity: false,
+    ...e2eEmailUser,
-  isGuest: true,
+    id: "user_e2e_messenger",
-  user: e2eUser,
+    username: "E2E Messenger User",
-  userId: e2eUser.id,
+    email: "messenger_hash@messenger.cozsweet.invalid",
+    loginProvider: "facebook_messenger",
+  },
 };

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 {
+import { clearBrowserState } from "@e2e/fixtures/test-helpers";
-  clearBrowserState,
-  defaultCharacterChatUrl,
-} 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(
+  const handoffRequestPromise = page.waitForRequest(
-    "**/api/auth/login/facebook/psid",
+    "**/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;
+  const handoffRequest = await handoffRequestPromise;
-  expect(psidLoginRequest.method()).toBe("POST");
+  expect(handoffRequest.method()).toBe("POST");
-  expect(psidLoginRequest.postDataJSON()).toMatchObject({
+  expect(handoffRequest.postDataJSON()).toEqual({ handoffToken });
-    psid,
-    bindToGuest: true,
-  });
-  expect(psidLoginRequest.postDataJSON().deviceId).toEqual(expect.any(String));
 
-  await expect(page).toHaveURL(defaultCharacterChatUrl);
+  await expect(page).toHaveURL("/subscription?type=topup");
-  await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+  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"),
+        loginToken: localStorage.getItem("cozsweet:login_token"),
-        psid: localStorage.getItem("cozsweet:psid"),
+        refreshToken: localStorage.getItem("cozsweet:refresh_token"),
       })),
     )
     .toMatchObject({
-      loginProvider: "guest",
+      loginProvider: "facebookMessenger",
-      guestToken: "e2e-psid-guest-token",
+      loginToken: "e2e-messenger-token",
-      psid,
+      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/commercial-action-navigation.spec.ts

@@ -4,7 +4,6 @@ import { mockCoreApis } from "@e2e/fixtures/api-mocks";
 import {
   clearBrowserState,
   enterChatFromSplash,
-  expectAuthRedirectToVipChatSubscription,
 } from "@e2e/fixtures/test-helpers";
 
 test.beforeEach(async ({ baseURL, context, page }) => {
@@ -44,12 +43,7 @@ test("asks for consent before opening a user-bound discount plan", async ({
   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(/\/auth\?redirect=/);
+  await expect(page).toHaveURL(
-  expectAuthRedirectToVipChatSubscription(page);
+    /\/subscription\?type=vip.*planId=vip_annual.*commercialOfferId=13ec8a10/,
-  const redirect = new URL(page.url()).searchParams.get("redirect");
-  const subscriptionUrl = new URL(redirect ?? "", "http://e2e.local");
-  expect(subscriptionUrl.searchParams.get("planId")).toBe("vip_annual");
-  expect(subscriptionUrl.searchParams.get("commercialOfferId")).toBe(
-    "13ec8a10-58d7-4d24-b66b-8db5699a1aa8",
   );
 });

e2e/specs/mock/chat/facebook-external-entry-links.spec.ts

@@ -0,0 +1,201 @@
+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 testPsid = "e2e-facebook-psid-27511427698460020";
+
+const characters = [
+  {
+    id: "elio",
+    slug: "elio",
+    displayName: "Elio Silvestri",
+    shortName: "Elio",
+  },
+  {
+    id: "maya-tan",
+    slug: "maya",
+    displayName: "Maya Tan",
+    shortName: "Maya",
+  },
+  {
+    id: "nayeli-cervantes",
+    slug: "nayeli",
+    displayName: "Nayeli Cervantes",
+    shortName: "Nayeli",
+  },
+] as const;
+
+type Character = (typeof characters)[number];
+type EntryKind = "private-space" | "voice" | "image-pack" | "coffee";
+
+interface FacebookEntryCase {
+  character: Character;
+  kind: EntryKind;
+  target: "chat" | "private-zone" | "tip";
+  expectedPath: string;
+  promotionType?: "voice";
+}
+
+const entryCases: FacebookEntryCase[] = characters.flatMap((character) => [
+  {
+    character,
+    kind: "private-space",
+    target: "chat",
+    expectedPath: `/characters/${character.slug}/chat`,
+  },
+  {
+    character,
+    kind: "voice",
+    target: "chat",
+    expectedPath: `/characters/${character.slug}/chat`,
+    promotionType: "voice",
+  },
+  {
+    character,
+    kind: "image-pack",
+    target: "private-zone",
+    expectedPath: `/characters/${character.slug}/private-zone`,
+  },
+  {
+    character,
+    kind: "coffee",
+    target: "tip",
+    expectedPath: `/characters/${character.slug}/tip`,
+  },
+]);
+
+test.beforeEach(async ({ baseURL, context, page }) => {
+  await clearBrowserState(context, page, baseURL);
+  await mockCoreApis(page);
+  await registerEntryPageMocks(page);
+});
+
+for (const entryCase of entryCases) {
+  test(`${entryCase.character.displayName} opens Facebook ${entryCase.kind} entry`, async ({
+    page,
+  }) => {
+    await page.goto(buildEntryUrl(entryCase));
+
+    await expect(page).toHaveURL(entryCase.expectedPath, { timeout: 20_000 });
+    await expect
+      .poll(() =>
+        page.evaluate(() => localStorage.getItem("cozsweet:psid")),
+      )
+      .toBe(testPsid);
+
+    if (entryCase.kind === "private-space") {
+      await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+      await expect(
+        page.getByRole("button", { name: "Unlock voice message" }),
+      ).toHaveCount(0);
+      return;
+    }
+
+    if (entryCase.kind === "voice") {
+      await expect(page.getByRole("textbox", { name: "Message" })).toBeVisible();
+      await expect(
+        page.getByRole("button", { name: "Unlock voice message" }),
+      ).toHaveCount(1);
+      return;
+    }
+
+    if (entryCase.kind === "image-pack") {
+      await expect(
+        page.getByRole("heading", { name: "Private albums" }),
+      ).toBeVisible();
+      await expect(
+        page.getByText(entryCase.character.displayName).last(),
+      ).toBeVisible();
+      return;
+    }
+
+    await expect(
+      page.getByRole("heading", {
+        name: `Buy ${entryCase.character.shortName} a coffee`,
+      }),
+    ).toBeVisible();
+  });
+}
+
+function buildEntryUrl(entryCase: FacebookEntryCase): string {
+  const params = new URLSearchParams({
+    target: entryCase.target,
+    character: entryCase.character.slug,
+    psid: testPsid,
+  });
+  if (entryCase.promotionType) {
+    params.set("mode", "promotion");
+    params.set("promotion_type", entryCase.promotionType);
+  }
+  return `/external-entry?${params.toString()}`;
+}
+
+async function registerEntryPageMocks(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) => {
+    await route.fulfill({
+      json: apiEnvelope({
+        creditBalance: 1000,
+        pendingImageCount: 0,
+        hasIncompleteContent: false,
+        items: [],
+      }),
+    });
+  });
+
+  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/chat/paid-image-promotion-topup.spec.ts

@@ -26,10 +26,7 @@ test("guest unlocks a promoted image through email login and top-up", async ({
   );
   await expect(page).toHaveURL(defaultCharacterChatUrl);
 
-  const promotedImageCard = page
+  const unlockButton = page.getByRole("button", {
-    .getByRole("group", { name: "Locked private image" })
-    .last();
-  const unlockButton = promotedImageCard.getByRole("button", {
     name: "Unlock private image",
   });
   await expect(unlockButton).toBeVisible({ timeout: 10_000 });

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

@@ -182,7 +182,7 @@ async function registerFavoriteMenuMocks(page: Page): Promise<void> {
 
 function collectBrowserErrors(page: Page): string[] {
   const errors: string[] = [];
-  page.on("pageerror", (error) => errors.push(error.stack ?? error.message));
+  page.on("pageerror", (error) => errors.push(error.message));
   page.on("console", (message) => {
     if (message.type() === "error") errors.push(message.text());
   });
@@ -193,8 +193,7 @@ 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") ||
+    message.includes("[Result] Result.wrap caught exception");
-    message.includes("Cannot read properties of undefined (reading 'waiting')");
   return !isKnownLocalPreviewDependencyError;
 }
 

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

@@ -107,13 +107,14 @@ for (const character of characters) {
     await page.goto(`/characters/${character.slug}/private-zone`);
 
     await Promise.all([momentsRequest, albumRequest]);
-    await expect(
-      page.getByRole("heading", { name: "Private moments" }),
-    ).toBeVisible();
-    await page.getByRole("tab", { name: "Albums" }).click();
     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}`,
@@ -163,7 +164,6 @@ test("a real Private Zone request failure still offers Retry", async ({
 
   await page.goto("/characters/maya/private-zone");
 
-  await page.getByRole("tab", { name: "Albums" }).click();
   await expect(page.getByRole("button", { name: "Retry" })).toBeVisible();
   await expect(page.getByRole("button", { name: "Refresh" })).toHaveCount(0);
 });

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/indonesia-qris.spec.ts

@@ -0,0 +1,422 @@
+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;
+      payChannel: "ezpay" | "stripe";
+    };
+    const plan =
+      idrPlans.plans.find((item) => item.planId === body.planId) ??
+      idrGiftCatalog.plans.find((item) => item.planId === body.planId);
+    const orderId = `order_${body.payChannel}_${body.planId}`;
+    orderStatuses.set(orderId, "pending");
+    orderPlans.set(orderId, {
+      planId: body.planId,
+      orderType: plan?.orderType ?? "dol",
+    });
+    await route.fulfill({
+      json: apiEnvelope({
+        orderId,
+        payParams:
+          body.payChannel === "stripe"
+            ? {
+                provider: "stripe",
+                clientSecret: "pi_e2e_secret_mock",
+              }
+            : {
+                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_ezpay_${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).toBeDisabled();
+  await expectCheckoutButtonLayout(page);
+
+  await page.getByRole("button", { name: /Monthly, 195900 IDR/i }).click();
+  const renewalDialog = page.getByRole("dialog", {
+    name: "Automatic Renewal Confirmation",
+  });
+  await expect(renewalDialog).toBeVisible();
+  expect(payment.getCreateOrderCount()).toBe(0);
+
+  await renewalDialog.getByRole("button", { name: "Confirm" }).click();
+  await expect(renewalDialog).toBeHidden();
+  await expect(checkoutButton).toBeEnabled();
+  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("closing QRIS allows switching to Stripe and creating a Stripe order", 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();
+
+  const stripeButton = page.getByRole("button", {
+    name: "Stripe",
+    exact: true,
+  });
+  await expect(stripeButton).toBeEnabled();
+  await stripeButton.click();
+  await expect(stripeButton).toHaveAttribute("aria-pressed", "true");
+  await expect(
+    page.getByRole("button", { name: "Resume QRIS payment" }),
+  ).toHaveCount(0);
+
+  const stripeRequestPromise = page.waitForRequest(
+    "**/api/payment/create-order",
+  );
+  await page.getByRole("button", { name: "Pay and Top Up" }).click();
+  const stripeRequest = await stripeRequestPromise;
+  expect(stripeRequest.postDataJSON()).toMatchObject({
+    planId: "dol_1000",
+    payChannel: "stripe",
+    recipientCharacterId: "elio",
+  });
+  expect(payment.getCreateOrderCount()).toBe(2);
+});
+
+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/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

@@ -17,7 +17,7 @@ test.beforeEach(async ({ baseURL, context, page }) => {
   await registerPrivateZoneVideoMocks(page);
 });
 
-test("Private Zone defaults to Moments and reveals video only after one credit unlock", async ({
+test("Private Zone defaults to Albums and reveals video after switching to Moments", async ({
   page,
 }) => {
   await seedEmailSession(page);
@@ -32,6 +32,11 @@ test("Private Zone defaults to Moments and reveals video only after one credit u
   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();
@@ -53,16 +58,29 @@ test("Private Zone defaults to Moments and reveals video only after one credit u
   await expect(page.getByRole("alertdialog")).toHaveCount(0);
 });
 
-test("Albums remain available behind the second tab", async ({ page }) => {
+test("Albums render first and Moments remain available behind the second tab", async ({ page }) => {
   await seedEmailSession(page);
   await page.goto("/characters/maya/private-zone");
 
-  await page.getByRole("tab", { name: "Albums" }).click();
+  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> {

package.json

@@ -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",

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: {}

scripts/contracts/__tests__/domestic-test-workflow.test.mjs

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const workflowUrl = new URL(
+  "../../../.gitea/workflows/domestic-test.yml",
+  import.meta.url,
+);
+const deployScriptUrl = new URL(
+  "../../server/deploy-domestic-test-archive.sh",
+  import.meta.url,
+);
+
+test("domestic frontend workflow is manual and registry-free", async () => {
+  const workflow = await readFile(workflowUrl, "utf8");
+
+  assert.match(workflow, /workflow_dispatch:/);
+  assert.doesNotMatch(workflow, /\bpush:/);
+  assert.doesNotMatch(workflow, /REGISTRY_IMAGE/);
+  assert.match(workflow, /docker save/);
+  assert.match(workflow, /DOMESTIC_TEST_SSH_PRIVATE_KEY_B64/);
+  assert.match(workflow, /base64 -d/);
+});
+
+test("domestic frontend workflow pins the China test API and isolated port", async () => {
+  const workflow = await readFile(workflowUrl, "utf8");
+  const deployScript = await readFile(deployScriptUrl, "utf8");
+
+  assert.match(workflow, /https:\/\/testapi\.banlv-ai\.com/);
+  assert.match(workflow, /wss:\/\/testapi\.banlv-ai\.com\/ws/);
+  assert.match(workflow, /9135/);
+  assert.match(deployScript, /127\.0\.0\.1:\$HOST_PORT/);
+  assert.match(deployScript, /cozsweet-frontend-domestic-test/);
+});

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（pre）→ push_to_remote "gitea" "pre"
+#        deploy_web_test.sh（test）→ push_to_remote "gitea" "test"
 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" "pre"
+    push_to_remote "gitea" "test"
 }
 
 main

scripts/release/pre_release_web.sh

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

scripts/server/deploy-domestic-test-archive.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ARCHIVE="${1:-}"
+IMAGE="${2:-}"
+ENV_FILE="${3:-}"
+HOST_PORT="${4:-9135}"
+CONTAINER_NAME="cozsweet-frontend-domestic-test"
+INTERNAL_PORT="3000"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SERVICE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SHARED_ROOT="$SERVICE_ROOT/shared"
+RELEASE_ROOT="$SERVICE_ROOT/releases/docker"
+
+if [ -z "$ARCHIVE" ] || [ -z "$IMAGE" ] || [ -z "$ENV_FILE" ]; then
+  echo "Usage: $0 <image-archive> <image> <env-file> [host-port]" >&2
+  exit 64
+fi
+if [ "$HOST_PORT" != "9135" ]; then
+  echo "Domestic frontend test must use isolated host port 9135" >&2
+  exit 64
+fi
+case "$ENV_FILE" in
+  "$SHARED_ROOT"/*) ;;
+  *)
+    echo "Environment file must be stored under $SHARED_ROOT" >&2
+    exit 64
+    ;;
+esac
+if [ ! -s "$ARCHIVE" ] || [ ! -s "$ENV_FILE" ]; then
+  echo "Image archive or environment file is missing" >&2
+  exit 66
+fi
+
+mkdir -p "$RELEASE_ROOT"
+chmod 700 "$SHARED_ROOT"
+gzip -dc "$ARCHIVE" | docker load >/dev/null
+docker image inspect "$IMAGE" >/dev/null
+
+old_image_id=""
+old_image_ref=""
+if docker container inspect "$CONTAINER_NAME" >/dev/null 2>&1; then
+  old_image_id="$(docker inspect -f '{{.Image}}' "$CONTAINER_NAME")"
+  old_image_ref="$(docker inspect -f '{{.Config.Image}}' "$CONTAINER_NAME")"
+elif ss -ltnH "sport = :$HOST_PORT" 2>/dev/null | grep -q .; then
+  echo "Host port $HOST_PORT is already used by another service" >&2
+  exit 69
+fi
+
+run_container() {
+  local image_ref="$1"
+  docker run -d \
+    --name "$CONTAINER_NAME" \
+    --restart unless-stopped \
+    -p "127.0.0.1:$HOST_PORT:$INTERNAL_PORT" \
+    --env-file "$ENV_FILE" \
+    -e "PORT=$INTERNAL_PORT" \
+    "$image_ref" >/dev/null
+}
+
+wait_healthy() {
+  local deadline=$((SECONDS + 180))
+  while [ "$SECONDS" -le "$deadline" ]; do
+    state="$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}' "$CONTAINER_NAME" 2>/dev/null || true)"
+    status="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:$HOST_PORT/" 2>/dev/null || true)"
+    if [[ "$status" =~ ^(200|204|301|302|303|307|308)$ ]] && { [ "$state" = "healthy" ] || [ "$state" = "running" ]; }; then
+      return 0
+    fi
+    sleep 2
+  done
+  return 1
+}
+
+docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+deployment_ok="1"
+if ! run_container "$IMAGE"; then
+  deployment_ok="0"
+elif ! wait_healthy; then
+  deployment_ok="0"
+fi
+
+if [ "$deployment_ok" != "1" ]; then
+  docker logs --tail 120 "$CONTAINER_NAME" >&2 || true
+  docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+  if [ -n "$old_image_id" ] && docker image inspect "$old_image_id" >/dev/null 2>&1; then
+    echo "New container failed health checks; restoring previous image" >&2
+    run_container "$old_image_id"
+    wait_healthy || true
+  fi
+  exit 1
+fi
+
+created_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+image_id="$(docker image inspect "$IMAGE" -f '{{.Id}}')"
+record="{\"createdAt\":\"$created_at\",\"environment\":\"domestic-test\",\"image\":\"$IMAGE\",\"imageId\":\"$image_id\",\"container\":\"$CONTAINER_NAME\",\"hostPort\":$HOST_PORT}"
+if [ -f "$RELEASE_ROOT/current.json" ]; then
+  cp "$RELEASE_ROOT/current.json" "$RELEASE_ROOT/previous.json"
+fi
+printf '%s\n' "$record" > "$RELEASE_ROOT/current.json"
+printf '%s\n' "$record" >> "$RELEASE_ROOT/releases.jsonl"
+
+echo "Domestic frontend test is healthy"
+echo "container=$CONTAINER_NAME"
+echo "host_port=$HOST_PORT"
+echo "image=$IMAGE"
+if [ -n "$old_image_ref" ]; then
+  echo "previous_image=$old_image_ref"
+fi

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/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/payment/__tests__/payment-launch-dialogs.test.tsx

@@ -1,23 +1,47 @@
-import { renderToStaticMarkup } from "react-dom/server";
+import { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+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,
 };
 
 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(
+    act(() =>
-      renderToStaticMarkup(
+      root.render(
         <PaymentLaunchDialogs
           currentOrderId={null}
           externalCheckoutAnalyticsKey="payment.external_checkout"
@@ -25,11 +49,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", () => {
+  it("portals the shared Ezpay confirmation outside transformed checkout UI", () => {
-    const html = renderToStaticMarkup(
+    act(() =>
+      root.render(
         <PaymentLaunchDialogs
           currentOrderId="order-123"
           externalCheckoutAnalyticsKey="tip.external_checkout"
@@ -40,13 +68,126 @@ describe("PaymentLaunchDialogs", () => {
             shouldShowEzpayConfirmDialog: true,
           }}
         />,
+      ),
     );
 
-    expect(html).toContain('role="alertdialog"');
+    const dialog = document.body.querySelector('[role="alertdialog"]');
-    expect(html).toContain("Continue to GCash?");
+    expect(dialog).not.toBeNull();
-    expect(html).toContain("Your coffee order is ready.");
+    expect(container.contains(dialog)).toBe(false);
-    expect(html).toContain("Order No. order-123");
+    expect(dialog?.parentElement?.parentElement).toBe(document.body);
-    expect(html).toContain('data-analytics-key="tip.external_checkout"');
+    expect(dialog?.textContent).toContain("Continue to payment?");
-    expect(html).toContain("Opening...");
+    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

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

@@ -0,0 +1,63 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { StripePaymentDialogLoading } from "../lazy-stripe-payment-dialog";
+import { StripePaymentDialog } from "../stripe-payment-dialog";
+
+describe("Stripe payment portal states", () => {
+  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("portals the unavailable state and keeps its explicit close action", () => {
+    const onClose = vi.fn();
+
+    act(() =>
+      root.render(
+        <StripePaymentDialog
+          clientSecret="client-secret"
+          onClose={onClose}
+        />,
+      ),
+    );
+
+    const dialog = document.body.querySelector('[role="alertdialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Payment unavailable");
+    expect(dialog?.getAttribute("aria-labelledby")).toBeTruthy();
+    expect(dialog?.getAttribute("aria-describedby")).toBeTruthy();
+
+    const okButton = Array.from(dialog?.querySelectorAll("button") ?? []).find(
+      (button) => button.textContent === "OK",
+    );
+    act(() => okButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("portals the lazy loading state", () => {
+    act(() => root.render(<StripePaymentDialogLoading />));
+
+    const dialog = document.body.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(container.contains(dialog)).toBe(false);
+    expect(dialog?.textContent).toContain("Preparing secure payment");
+    expect(dialog?.textContent).toContain("Loading payment methods...");
+    expect(dialog?.querySelector('[aria-busy="true"]')).not.toBeNull();
+  });
+});

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
+    <ModalPortal
-      className={styles.overlay}
+      open
-      role="dialog"
+      persistent
-      aria-modal="true"
+      onClose={() => undefined}
-      aria-labelledby="stripe-payment-loading-title"
+      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>
+          <p id="stripe-payment-loading-description" className={styles.content}>
-        </div>
+            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,10 +13,15 @@ type PaymentLaunchDialogFlow = Pick<
   PaymentLaunchFlow,
   | "handleEzpayCancel"
   | "handleEzpayConfirm"
+  | "handleRegionalQrClose"
   | "handleStripeClose"
   | "handleStripeConfirmed"
   | "isConfirmingEzpay"
+  | "regionalQrErrorMessage"
+  | "regionalQrPayment"
+  | "regionalQrStatus"
   | "shouldShowEzpayConfirmDialog"
+  | "shouldShowRegionalQrDialog"
   | "shouldShowStripeDialog"
   | "stripeClientSecret"
 >;
@@ -46,6 +53,14 @@ 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}
@@ -58,6 +73,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 +238,19 @@ function EzpayRedirectConfirmDialog({
   const titleId = useId();
 
   return (
-    <div
+    <ModalPortal
-      className={styles.overlay}
+      open
+      persistent
+      onClose={onCancel}
+      scrimClassName={styles.overlay}
+      panelClassName={styles.dialog}
+      scrimOpacity={0.5}
       role="alertdialog"
-      aria-modal="true"
+      ariaLabelledBy={titleId}
-      aria-labelledby={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 +275,6 @@ function EzpayRedirectConfirmDialog({
           {isConfirming ? "Opening..." : "Continue"}
         </button>
       </div>
-      </div>
+    </ModalPortal>
-    </div>
   );
 }

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

@@ -44,13 +44,24 @@ 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

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

@@ -2,7 +2,7 @@ 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",

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

@@ -4,7 +4,7 @@
  *
  * 后端当前返回 PaymentIntent clientSecret，因此这里直接用它完成前端确认。
  */
-import { useState, type FormEvent } from "react";
+import { useId, useState, type FormEvent } from "react";
 import {
   Elements,
   PaymentElement,
@@ -13,6 +13,7 @@ import {
 } from "@stripe/react-stripe-js";
 import { loadStripe } 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";
@@ -38,13 +39,27 @@ export function StripePaymentDialog({
   onClose,
   onConfirmed,
 }: StripePaymentDialogProps) {
+  const titleId = useId();
+  const descriptionId = useId();
+
   if (!stripePromise) {
     return (
-      <div className={styles.overlay} role="alertdialog" aria-modal="true">
+      <ModalPortal
-        <div className={styles.dialog}>
+        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>
+          <h2 id={titleId} className={styles.title}>
-            <p className={styles.content}>
+            Payment unavailable
+          </h2>
+          <p id={descriptionId} className={styles.content}>
             Stripe publishable key is not configured for this build.
           </p>
         </div>
@@ -57,24 +72,26 @@ export function StripePaymentDialog({
             OK
           </button>
         </div>
-        </div>
+      </ModalPortal>
-      </div>
     );
   }
 
   return (
-    <div
+    <ModalPortal
-      className={styles.overlay}
+      open
-      role="dialog"
+      persistent
-      aria-modal="true"
+      onClose={onClose}
-      aria-labelledby="stripe-payment-title"
+      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>
@@ -99,8 +116,7 @@ export function StripePaymentDialog({
           onConfirmed={onConfirmed}
         />
       </Elements>
-      </div>
+    </ModalPortal>
-    </div>
   );
 }
 

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

@@ -4,9 +4,11 @@ import { type Dispatch, useEffect, useRef, useState } from "react";
 
 import {
   getPaymentUrl,
+  getPaymentUrlHostname,
   getStripeClientSecret,
   isEzpayPayment,
   launchEzpayRedirect,
+  resolveEzpayLaunchTarget,
 } from "@/lib/payment/payment_launch";
 import { behaviorAnalytics } from "@/lib/analytics";
 import type {
@@ -40,21 +42,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;
 }
 
+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(
   payment: PaymentContextState,
   checkoutUrl: string,
@@ -112,6 +156,7 @@ export function usePaymentLaunchFlow({
   subscriptionType,
   giftCategory,
   giftPlanId,
+  countryCode,
 }: UsePaymentLaunchFlowInput): PaymentLaunchFlow {
   const launchedNonceRef = useRef(0);
   const [hiddenStripeClientSecret, setHiddenStripeClientSecret] = useState<
@@ -121,8 +166,41 @@ export function usePaymentLaunchFlow({
   const stripeClientSecret = payment.payParams
     ? getStripeClientSecret(payment.payParams)
     : null;
-  const ezpayPaymentUrl = payment.payParams
+  const selectedPlan = payment.plans.find(
-    ? getPaymentUrl(payment.payParams)
+    (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 +214,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 +299,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 +323,7 @@ export function usePaymentLaunchFlow({
     log,
     logScope,
     characterSlug,
+    countryCode,
     payment.currentOrderId,
     payment,
     payment.launchNonce,
@@ -197,6 +332,7 @@ export function usePaymentLaunchFlow({
     payment.plans,
     payment.selectedPlanId,
     paymentDispatch,
+    paymentCurrency,
     returnTo,
     subscriptionType,
     giftCategory,
@@ -213,6 +349,9 @@ export function usePaymentLaunchFlow({
     payParams: payment.payParams,
     paymentUrl: ezpayPaymentUrl,
   });
+  const shouldShowRegionalQrDialog = Boolean(
+    regionalQrPayment && !payment.isPaid,
+  );
 
   function resetLaunchState(): void {
     setIsConfirmingEzpay(false);
@@ -263,15 +402,29 @@ 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,
   };

src/app/chat/__tests__/chat-support-cta.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import { deriveChatSupportCta } from "../chat-support-cta";
+
+describe("deriveChatSupportCta", () => {
+  const now = Date.parse("2026-07-28T00:00:00.000Z");
+
+  it("shows first recharge ahead of a weaker role offer without inventing a timer", () => {
+    expect(
+      deriveChatSupportCta({
+        isFirstRecharge: true,
+        commercialOffer: {
+          enabled: true,
+          commercialOfferId: "offer-1",
+          characterId: "elio",
+          planId: "vip_annual",
+          discountPercent: 30,
+          pricePercent: 70,
+          expiresAt: "2026-07-29T00:00:00.000Z",
+          triggerReason: "price_objection",
+          message: "I got this for you.",
+        },
+        nowMs: now,
+      }),
+    ).toMatchObject({
+      kind: "firstRecharge",
+      label: "Support me · 50% OFF · First recharge",
+      commercialOfferId: null,
+      expiresAt: null,
+    });
+  });
+
+  it("shows a server-anchored 24-hour role offer countdown", () => {
+    expect(
+      deriveChatSupportCta({
+        isFirstRecharge: false,
+        commercialOffer: {
+          enabled: true,
+          commercialOfferId: "offer-1",
+          characterId: "maya-tan",
+          planId: "vip_annual",
+          discountPercent: 30,
+          pricePercent: 70,
+          expiresAt: "2026-07-29T00:00:00.000Z",
+          triggerReason: "price_objection",
+          message: "I got this for you.",
+        },
+        nowMs: now,
+      }),
+    ).toMatchObject({
+      kind: "commercialOffer",
+      label: "Support me · 30% OFF · 23:59:59",
+      commercialOfferId: "offer-1",
+      expiresAt: "2026-07-29T00:00:00.000Z",
+    });
+  });
+
+  it("returns to Support me after an offer expires or is absent", () => {
+    expect(
+      deriveChatSupportCta({
+        isFirstRecharge: false,
+        commercialOffer: null,
+        nowMs: now,
+      }).label,
+    ).toBe("Support me");
+    expect(
+      deriveChatSupportCta({
+        isFirstRecharge: false,
+        commercialOffer: {
+          enabled: true,
+          commercialOfferId: "offer-1",
+          characterId: "elio",
+          planId: "vip_annual",
+          discountPercent: 30,
+          pricePercent: 70,
+          expiresAt: "2026-07-27T00:00:00.000Z",
+          triggerReason: "price_objection",
+          message: "I got this for you.",
+        },
+        nowMs: now,
+      }).label,
+    ).toBe("Support me");
+  });
+});

src/app/chat/chat-screen.tsx

@@ -33,8 +33,8 @@ import {
   ChatHeader,
   ChatInputBar,
   ChatInsufficientCreditsBanner,
+  ChatSupportButton,
   ChatUnlockDialogs,
-  FirstRechargeOfferBanner,
   FullscreenImageViewer,
   PwaInstallOverlay,
 } from "./components";
@@ -46,7 +46,8 @@ import {
 import {
   deriveIsGuest,
 } from "./chat-screen.helpers";
-import { useFirstRechargeOfferBanner } from "./hooks/use-first-recharge-offer-banner";
+import { useChatSupportCta } from "./hooks/use-chat-support-cta";
+import { useChatCommercialMessages } from "./hooks/use-chat-commercial-messages";
 import { useChatUnlockCoordinator } from "./hooks/use-chat-unlock-coordinator";
 import { useChatGuestLogin } from "./hooks/use-chat-guest-login";
 import { useChatMessageLimitBanner } from "./hooks/use-chat-message-limit-banner";
@@ -128,11 +129,17 @@ export function ChatScreen() {
   const messageLimitBanner = useChatMessageLimitBanner({
     upgradePromptVisible: state.upgradePromptVisible,
     upgradeReason: state.upgradeReason,
+    paymentGuidance: state.paymentGuidance,
   });
-  const firstRechargeOfferBanner = useFirstRechargeOfferBanner({
+  const supportCta = useChatSupportCta({
+    characterId: character.id,
     historyLoaded: state.historyLoaded,
     loginStatus: authState.loginStatus,
   });
+  useChatCommercialMessages({
+    characterId: character.id,
+    loginStatus: authState.loginStatus,
+  });
   const shouldShowPwaInstall =
     state.historyLoaded && state.historyMessages.length >= 10;
   useChatGuestLogin({
@@ -421,13 +428,13 @@ export function ChatScreen() {
           <ChatHeader
             isGuest={isGuest}
             offerBanner={
-              <FirstRechargeOfferBanner
+              supportCta.visible ? (
-                visible={firstRechargeOfferBanner.visible}
+                <ChatSupportButton
-                discountPercent={firstRechargeOfferBanner.discountPercent}
+                  kind={supportCta.kind}
-                onClick={firstRechargeOfferBanner.claim}
+                  label={supportCta.label}
-                onClose={firstRechargeOfferBanner.close}
+                  onClick={supportCta.open}
-                variant="compact"
                 />
+              ) : null
             }
           />
 
@@ -464,6 +471,7 @@ export function ChatScreen() {
               title={messageLimitBanner.title}
               description={messageLimitBanner.description}
               ctaLabel={messageLimitBanner.ctaLabel}
+              guidance={messageLimitBanner.guidance}
               onUnlock={messageLimitBanner.unlock}
             />
           ) : (

src/app/chat/chat-support-cta.ts

@@ -0,0 +1,63 @@
+import type { CommercialOfferSummary } from "@/data/schemas/payment";
+
+export type ChatSupportCtaKind =
+  | "support"
+  | "firstRecharge"
+  | "commercialOffer";
+
+export interface ChatSupportCtaView {
+  kind: ChatSupportCtaKind;
+  label: string;
+  commercialOfferId: string | null;
+  planId: string | null;
+  expiresAt: string | null;
+}
+
+export function deriveChatSupportCta(input: {
+  isFirstRecharge: boolean;
+  commercialOffer: CommercialOfferSummary | null;
+  nowMs: number;
+}): ChatSupportCtaView {
+  if (input.isFirstRecharge) {
+    return {
+      kind: "firstRecharge",
+      label: "Support me · 50% OFF · First recharge",
+      commercialOfferId: null,
+      planId: null,
+      expiresAt: null,
+    };
+  }
+
+  const offer = input.commercialOffer;
+  const expiresAtMs = offer ? Date.parse(offer.expiresAt) : Number.NaN;
+  if (offer?.enabled && Number.isFinite(expiresAtMs) && expiresAtMs > input.nowMs) {
+    return {
+      kind: "commercialOffer",
+      label: `Support me · ${offer.discountPercent}% OFF · ${formatOfferCountdown(expiresAtMs, input.nowMs)}`,
+      commercialOfferId: offer.commercialOfferId,
+      planId: offer.planId,
+      expiresAt: offer.expiresAt,
+    };
+  }
+
+  return {
+    kind: "support",
+    label: "Support me",
+    commercialOfferId: null,
+    planId: null,
+    expiresAt: null,
+  };
+}
+
+export function formatOfferCountdown(expiresAtMs: number, nowMs: number): string {
+  const totalSeconds = Math.max(
+    0,
+    Math.ceil((expiresAtMs - nowMs) / 1000) - 1,
+  );
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return [hours, minutes, seconds]
+    .map((value) => String(value).padStart(2, "0"))
+    .join(":");
+}

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

@@ -15,6 +15,7 @@ import { ImageBubble } from "../image-bubble";
 import { InsufficientCreditsDialog } from "../insufficient-credits-dialog";
 import { MessageAvatar } from "../message-avatar";
 import { PrivateMessageCard } from "../private-message-card";
+import { PaymentGuidanceCard } from "../payment-guidance-card";
 import { PwaInstallDialog } from "../pwa-install-dialog";
 import { TextBubble } from "../text-bubble";
 
@@ -223,6 +224,19 @@ describe("chat Tailwind components", () => {
         description="Credits keep the conversation going."
         ctaLabel="Top up"
         onUnlock={() => undefined}
+        guidance={{
+          guidanceId: "guidance-elio",
+          characterId: "elio",
+          characterName: "Elio Silvestri",
+          scene: "insufficientCredits",
+          mode: "guide",
+          title: "Keep talking with Elio",
+          copy: "Baby, I want to keep talking with you. Adding credits supports Elio.",
+          ctaLabel: "View VIP & credit options",
+          purchaseOptions: ["vip", "topup"],
+          target: "subscription",
+          ruleId: "payment_guidance_insufficientCredits",
+        }}
       />,
     );
 
@@ -232,11 +246,56 @@ describe("chat Tailwind components", () => {
     expect(html).toContain("<br/>");
     expect(html).toContain("Top up now");
     expect(html).toContain("Credits keep the conversation going.");
+    expect(html).toContain("supports Elio");
+    expect(html).toContain('data-payment-guidance-id="guidance-elio"');
     expect(html).toContain('aria-label="Top up"');
     expect(html).toContain("bg-[linear-gradient(135deg,#f96ade_0%,#f657a0_100%)]");
     expect(html).toContain("active:scale-98");
   });
 
+  it("renders guidance only for the active character and hides care-only CTA", () => {
+    const guide = {
+      guidanceId: "019c8f8d-17d3-7a42-b1cc-b6927b1927d5",
+      characterId: "elio",
+      characterName: "Elio Silvestri",
+      scene: "insufficientCredits" as const,
+      mode: "guide" as const,
+      title: "Keep talking with Elio",
+      copy: "Baby, I want to keep talking with you.",
+      ctaLabel: "View VIP & credit options",
+      purchaseOptions: ["vip", "topup"] as const,
+      target: "subscription" as const,
+      ruleId: "payment_guidance_insufficientCredits",
+    };
+    const guideHtml = renderWithCharacter(
+      <PaymentGuidanceCard guidance={guide} />,
+    );
+    const mismatchHtml = renderWithCharacter(
+      <PaymentGuidanceCard
+        guidance={{ ...guide, characterId: "maya-tan", characterName: "Maya Tan" }}
+      />,
+    );
+    const careHtml = renderWithCharacter(
+      <PaymentGuidanceCard
+        guidance={{
+          ...guide,
+          mode: "careOnly",
+          title: null,
+          ctaLabel: null,
+          purchaseOptions: [],
+          target: null,
+          copy: "Please keep money you need for food or medicine.",
+        }}
+      />,
+    );
+
+    expect(guideHtml).toContain('data-payment-guidance-mode="guide"');
+    expect(guideHtml).toContain("View VIP &amp; credit options");
+    expect(mismatchHtml).toBe("");
+    expect(careHtml).toContain("food or medicine");
+    expect(careHtml).not.toContain("View VIP");
+  });
+
   it("renders ChatHeader guest and member branches", () => {
     const guestHtml = renderWithCharacter(<ChatHeader isGuest={true} />);
     const memberHtml = renderWithCharacter(

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

@@ -337,6 +337,7 @@ function renderMessagesWithDateHeaders(
         privateMessageHint={item.message.privateMessageHint}
         commercialAction={item.message.commercialAction}
         chatAction={item.message.chatAction}
+        paymentGuidance={item.message.paymentGuidance}
         isUnlockingMessage={
           isUnlockingMessage === true &&
           item.message.displayId === unlockingMessageId

src/app/chat/components/chat-insufficient-credits-banner.tsx

@@ -17,11 +17,13 @@
  *   - 不直接管理 state machine（chat 机器不感知 UI 层）
  */
 import { useAppNavigator } from "@/router/use-app-navigator";
+import type { PaymentGuidance } from "@/data/schemas/chat";
 
 export interface ChatInsufficientCreditsBannerProps {
   title?: string;
   description?: string;
-  ctaLabel?: string;
+  ctaLabel?: string | null;
+  guidance?: PaymentGuidance | null;
   /**
    * 自定义点击回调（不传则默认走统一订阅导航）
    * - 测试时可传 mock
@@ -34,9 +36,11 @@ export function ChatInsufficientCreditsBanner({
   title = "Insufficient credits\nTop up to continue chatting",
   description,
   ctaLabel = "Top up credits to continue",
+  guidance = null,
   onUnlock,
 }: ChatInsufficientCreditsBannerProps) {
   const navigator = useAppNavigator();
+  const activeGuidance = guidance;
   const titleLines = title.split("\n");
 
   const handleClick = () => {
@@ -53,6 +57,7 @@ export function ChatInsufficientCreditsBanner({
       role="status"
       aria-live="polite"
       data-testid="chat-insufficient-credits-banner"
+      data-payment-guidance-id={activeGuidance?.guidanceId}
     >
       <p className="m-0 mb-(--spacing-sm,8px) text-(length:--responsive-card-title,18px) font-semibold leading-[1.4] text-white opacity-95">
         {titleLines.map((line, index) => (
@@ -67,7 +72,12 @@ export function ChatInsufficientCreditsBanner({
           {description}
         </p>
       ) : null}
-      <button
+      {activeGuidance?.copy ? (
+        <p className="mx-auto mb-(--spacing-lg,16px) mt-0 max-w-[min(100%,360px)] text-(length:--responsive-caption,14px) font-semibold leading-[1.4] text-white">
+          {activeGuidance.copy}
+        </p>
+      ) : null}
+      {ctaLabel ? <button
         type="button"
         data-analytics-key="chat.topup"
         data-analytics-label="Top up chat credits"
@@ -76,7 +86,7 @@ export function ChatInsufficientCreditsBanner({
         aria-label={ctaLabel}
       >
         {ctaLabel}
-      </button>
+      </button> : null}
     </div>
   );
 }

src/app/chat/components/chat-support-button.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { Heart, Sparkles } from "lucide-react";
+
+import type { ChatSupportCtaKind } from "../chat-support-cta";
+
+export interface ChatSupportButtonProps {
+  kind: ChatSupportCtaKind;
+  label: string;
+  onClick: () => void;
+}
+
+export function ChatSupportButton({
+  kind,
+  label,
+  onClick,
+}: ChatSupportButtonProps) {
+  const Icon = kind === "support" ? Heart : Sparkles;
+  return (
+    <button
+      type="button"
+      data-analytics-key="chat.support_character"
+      data-support-state={kind}
+      className="inline-flex min-h-9 max-w-full items-center justify-center gap-1.5 rounded-full border border-[rgba(255,255,255,0.22)] bg-[linear-gradient(135deg,rgba(246,87,160,0.96),rgba(255,119,84,0.94))] px-3 py-1.5 text-center text-[12px] font-extrabold leading-tight text-white shadow-[0_8px_24px_rgba(246,87,160,0.3)] backdrop-blur-md transition active:scale-95"
+      aria-label={label}
+      onClick={onClick}
+    >
+      <Icon className="shrink-0" size={14} strokeWidth={2.5} aria-hidden="true" />
+      <span className="whitespace-normal text-balance">{label}</span>
+    </button>
+  );
+}

src/app/chat/components/chat-unlock-dialogs.tsx

@@ -19,6 +19,7 @@ export function ChatUnlockDialogs({
         lockedCount={model.historyUnlock.lockedCount}
         isLoading={model.historyUnlock.isLoading}
         errorMessage={model.historyUnlock.errorMessage}
+        guidance={model.historyUnlock.guidance}
         onClose={model.closeHistoryUnlock}
         onConfirm={model.confirmHistoryUnlock}
       />
@@ -27,6 +28,7 @@ export function ChatUnlockDialogs({
         creditBalance={model.unlockPaywallRequest?.creditBalance ?? 0}
         requiredCredits={model.unlockPaywallRequest?.requiredCredits ?? 0}
         shortfallCredits={model.unlockPaywallRequest?.shortfallCredits ?? 0}
+        guidance={model.unlockPaywallRequest?.paymentGuidance ?? null}
         onClose={model.closePaywall}
         onConfirm={model.confirmPaywall}
       />

src/app/chat/components/history-unlock-dialog.tsx

@@ -1,10 +1,13 @@
 "use client";
 
+import type { PaymentGuidance } from "@/data/schemas/chat";
+
 export interface HistoryUnlockDialogProps {
   open: boolean;
   lockedCount: number;
   isLoading?: boolean;
   errorMessage?: string | null;
+  guidance?: PaymentGuidance | null;
   onClose: () => void;
   onConfirm: () => void;
 }
@@ -14,10 +17,15 @@ export function HistoryUnlockDialog({
   lockedCount,
   isLoading = false,
   errorMessage,
+  guidance = null,
   onClose,
   onConfirm,
 }: HistoryUnlockDialogProps) {
   if (!open) return null;
+  const activeGuidance = guidance;
+  const showAction =
+    !activeGuidance ||
+    (activeGuidance.mode === "guide" && activeGuidance.ctaLabel !== null);
 
   return (
     <div
@@ -31,11 +39,16 @@ export function HistoryUnlockDialog({
           id="history-unlock-title"
           className="m-0 mb-2.5 text-(length:--responsive-page-title,var(--font-size-22,22px)) font-bold leading-[1.2] text-text-foreground"
         >
-          Unlock previous messages?
+          {activeGuidance?.title ?? "Unlock previous messages?"}
         </h2>
         <p className="mx-(--responsive-card-padding-lg,24px) mb-(--spacing-lg,16px) mt-0 text-left text-(length:--responsive-body,var(--font-size-lg,16px)) leading-normal text-[#393939]">
-          We found {lockedCount} locked messages in your chat history. You can
+          {activeGuidance?.copy ?? (
-          unlock them now to continue the conversation with full context.
+            <>
+              We found {lockedCount} locked messages in your chat history. You
+              can unlock them now to continue the conversation with full
+              context.
+            </>
+          )}
         </p>
         {errorMessage ? (
           <p className="mx-(--responsive-card-padding-lg,24px) mb-(--spacing-lg,16px) mt-0 text-left text-(length:--responsive-caption,var(--font-size-md,14px)) leading-[1.4] text-[#c0364c]">
@@ -51,7 +64,7 @@ export function HistoryUnlockDialog({
           >
             Later
           </button>
-          <button
+          {showAction ? <button
             type="button"
             data-analytics-key="chat.unlock_history"
             data-analytics-label="Unlock chat history"
@@ -59,8 +72,10 @@ export function HistoryUnlockDialog({
             onClick={onConfirm}
             disabled={isLoading}
           >
-            {isLoading ? "Unlocking..." : "Unlock now"}
+            {isLoading
-          </button>
+              ? "Unlocking..."
+              : activeGuidance?.ctaLabel ?? "Unlock now"}
+          </button> : null}
         </div>
       </div>
     </div>

src/app/chat/components/index.ts

@@ -12,6 +12,7 @@ export * from "./chat-insufficient-credits-banner";
 export * from "./chat-input-bar";
 export * from "./chat-input-text-field";
 export * from "./chat-send-button";
+export * from "./chat-support-button";
 export * from "./chat-unlock-dialogs";
 export * from "./date-header";
 export * from "./first-recharge-offer-banner";
@@ -22,6 +23,7 @@ export * from "./insufficient-credits-dialog";
 export * from "./message-avatar";
 export * from "./message-bubble";
 export * from "./message-content";
+export * from "./payment-guidance-card";
 export * from "./private-message-card";
 export * from "./pwa-install-dialog";
 export * from "./pwa-install-overlay";

src/app/chat/components/insufficient-credits-dialog.tsx

@@ -1,10 +1,13 @@
 "use client";
 
+import type { PaymentGuidance } from "@/data/schemas/chat";
+
 export interface InsufficientCreditsDialogProps {
   open: boolean;
   creditBalance: number;
   requiredCredits: number;
   shortfallCredits: number;
+  guidance?: PaymentGuidance | null;
   onClose: () => void;
   onConfirm: () => void;
 }
@@ -14,12 +17,17 @@ export function InsufficientCreditsDialog({
   creditBalance,
   requiredCredits,
   shortfallCredits,
+  guidance = null,
   onClose,
   onConfirm,
 }: InsufficientCreditsDialogProps) {
   if (!open) return null;
 
   const showCreditDetail = requiredCredits > 0 || shortfallCredits > 0;
+  const activeGuidance = guidance;
+  const showPurchaseAction =
+    !activeGuidance ||
+    (activeGuidance.mode === "guide" && activeGuidance.ctaLabel !== null);
 
   return (
     <div
@@ -33,10 +41,11 @@ export function InsufficientCreditsDialog({
           id="insufficient-credits-title"
           className="m-0 mb-2.5 text-(length:--responsive-page-title,var(--font-size-22,22px)) font-bold leading-[1.2] text-text-foreground"
         >
-          Not enough credits
+          {activeGuidance?.title ?? "Not enough credits"}
         </h2>
         <p className="mx-(--spacing-md,12px) mb-(--page-section-gap,18px) mt-0 text-(length:--responsive-body,var(--font-size-lg,16px)) leading-normal text-[#393939]">
-          Top up your credits to unlock this message and keep the moment going.
+          {activeGuidance?.copy ??
+            "Top up your credits to unlock this message and keep the moment going."}
         </p>
 
         {showCreditDetail ? (
@@ -70,15 +79,15 @@ export function InsufficientCreditsDialog({
           >
             Later
           </button>
-          <button
+          {showPurchaseAction ? <button
             type="button"
             data-analytics-key="chat.topup"
             data-analytics-label="Top up chat credits"
             className="flex min-h-(--pwa-button-height,44px) flex-auto cursor-pointer items-center justify-center rounded-bottom-sheet border-0 bg-[linear-gradient(90deg,#ff67e0_0%,#ff52a2_100%)] text-(length:--responsive-body,var(--font-size-lg,16px)) font-bold text-(--color-pwa-button-text,#ffffff) shadow-[0_6px_14px_rgba(246,87,160,0.28)] focus-visible:outline-2 focus-visible:outline-offset-3 focus-visible:outline-[#f657a0]"
             onClick={onConfirm}
           >
-            Top up now
+            {activeGuidance?.ctaLabel ?? "Top up now"}
-          </button>
+          </button> : null}
         </div>
       </div>
     </div>

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

@@ -9,7 +9,7 @@
  *   - 用户：[占位 spacer] [Content] [Avatar]
  */
 import { useUserSelector } from "@/stores/user/user-context";
-import type { ChatAction, CommercialAction } from "@/data/schemas/chat";
+import type { ChatAction, CommercialAction, PaymentGuidance } from "@/data/schemas/chat";
 
 import { MessageAvatar } from "./message-avatar";
 import { MessageContent } from "./message-content";
@@ -30,6 +30,7 @@ export interface MessageBubbleProps {
   privateMessageHint?: string | null;
   commercialAction?: CommercialAction | null;
   chatAction?: ChatAction | null;
+  paymentGuidance?: PaymentGuidance | null;
   isUnlockingMessage?: boolean;
   onUnlockPrivateMessage?: ChatMessageAction;
   onUnlockVoiceMessage?: ChatMessageAction;
@@ -64,6 +65,7 @@ export function MessageBubble({
   privateMessageHint,
   commercialAction,
   chatAction,
+  paymentGuidance,
   isUnlockingMessage,
   onUnlockPrivateMessage,
   onUnlockVoiceMessage,
@@ -106,6 +108,7 @@ export function MessageBubble({
           privateMessageHint={privateMessageHint}
           commercialAction={commercialAction}
           chatAction={chatAction}
+          paymentGuidance={paymentGuidance}
           isUnlockingMessage={isUnlockingMessage}
           onUnlockPrivateMessage={onUnlockPrivateMessage}
           onUnlockVoiceMessage={onUnlockVoiceMessage}

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

@@ -1,11 +1,16 @@
 "use client";
-import type { ChatAction, CommercialAction } from "@/data/schemas/chat";
+import type {
+  ChatAction,
+  CommercialAction,
+  PaymentGuidance,
+} from "@/data/schemas/chat";
 
 import { ChatActionCard } from "./chat-action-card";
 import { CommercialActionCard } from "./commercial-action-card";
 import { ImageBubble } from "./image-bubble";
 import { LockedImageMessageCard } from "./locked-image-message-card";
 import { PrivateMessageCard } from "./private-message-card";
+import { PaymentGuidanceCard } from "./payment-guidance-card";
 import { TextBubble } from "./text-bubble";
 import { VoiceBubble } from "./voice-bubble";
 import styles from "./chat-area.module.css";
@@ -25,6 +30,7 @@ export interface MessageContentProps {
   privateMessageHint?: string | null;
   commercialAction?: CommercialAction | null;
   chatAction?: ChatAction | null;
+  paymentGuidance?: PaymentGuidance | null;
   isUnlockingMessage?: boolean;
   onUnlockPrivateMessage?: ChatMessageAction;
   onUnlockVoiceMessage?: ChatMessageAction;
@@ -59,6 +65,7 @@ export function MessageContent({
   privateMessageHint,
   commercialAction,
   chatAction,
+  paymentGuidance,
   isUnlockingMessage,
   onUnlockPrivateMessage,
   onUnlockVoiceMessage,
@@ -143,7 +150,9 @@ export function MessageContent({
           ) : null}
         </>
       )}
-      {isFromAI && chatAction ? (
+      {isFromAI && paymentGuidance ? (
+        <PaymentGuidanceCard guidance={paymentGuidance} />
+      ) : isFromAI && chatAction ? (
         <ChatActionCard
           action={chatAction}
           onViewed={onChatActionViewed}

src/app/chat/components/payment-guidance-card.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { ArrowRight, CircleDollarSign, X } from "lucide-react";
+
+import type { PaymentGuidance } from "@/data/schemas/chat";
+import type { PaymentAnalyticsTriggerReason } from "@/lib/analytics/payment_analytics_context";
+import { recordChatActionEventById } from "@/lib/chat/chat_action_events";
+import { useActiveCharacter } from "@/providers/character-provider";
+import { useAppNavigator } from "@/router/use-app-navigator";
+import { useUserSelector } from "@/stores/user/user-context";
+
+import styles from "./chat-area.module.css";
+
+export interface PaymentGuidanceCardProps {
+  guidance: PaymentGuidance;
+}
+
+function triggerReasonForGuidance(
+  scene: PaymentGuidance["scene"],
+): PaymentAnalyticsTriggerReason {
+  if (scene === "supportCharacter" || scene === "vip" || scene === "purchaseOptions") {
+    return "vip_cta";
+  }
+  if (scene === "privateMessageLocked" || scene === "historyLocked") {
+    return "private_topic_limit";
+  }
+  return "insufficient_credits";
+}
+
+export function PaymentGuidanceCard({ guidance }: PaymentGuidanceCardProps) {
+  const character = useActiveCharacter();
+  const navigator = useAppNavigator();
+  const isVip = useUserSelector((state) => state.context.isVip);
+  const [dismissed, setDismissed] = useState(false);
+  const viewedIdRef = useRef<string | null>(null);
+  const belongsToCurrentCharacter = guidance.characterId === character.id;
+  const hasPurchaseAction =
+    guidance.mode === "guide" &&
+    guidance.target === "subscription" &&
+    guidance.ctaLabel !== null &&
+    guidance.purchaseOptions.length > 0;
+
+  useEffect(() => {
+    if (!belongsToCurrentCharacter) return;
+    if (viewedIdRef.current === guidance.guidanceId) return;
+    viewedIdRef.current = guidance.guidanceId;
+    void recordChatActionEventById(
+      guidance.guidanceId,
+      character.id,
+      "viewed",
+    ).catch(() => undefined);
+  }, [belongsToCurrentCharacter, character.id, guidance.guidanceId]);
+
+  if (!belongsToCurrentCharacter || dismissed) return null;
+
+  const subscriptionType =
+    isVip || !guidance.purchaseOptions.includes("vip") ? "topup" : "vip";
+
+  return (
+    <aside
+      className={styles.commercialAction}
+      aria-label={guidance.title ?? guidance.characterName}
+      data-payment-guidance-id={guidance.guidanceId}
+      data-payment-guidance-mode={guidance.mode}
+      data-payment-guidance-scene={guidance.scene}
+    >
+      <div className={styles.commercialActionHeader}>
+        <CircleDollarSign size={18} aria-hidden="true" />
+        <button
+          type="button"
+          className={styles.commercialActionDismiss}
+          title="Dismiss"
+          aria-label="Dismiss"
+          onClick={() => {
+            setDismissed(true);
+            void recordChatActionEventById(
+              guidance.guidanceId,
+              character.id,
+              "dismissed",
+            ).catch(() => undefined);
+          }}
+        >
+          <X size={16} aria-hidden="true" />
+        </button>
+      </div>
+      {guidance.title ? (
+        <strong>{guidance.title}</strong>
+      ) : null}
+      <p className={styles.commercialActionCopy}>{guidance.copy}</p>
+      {hasPurchaseAction ? (
+        <button
+          type="button"
+          className={styles.commercialActionButton}
+          onClick={() => {
+            void recordChatActionEventById(
+              guidance.guidanceId,
+              character.id,
+              "opened",
+            ).catch(() => undefined);
+            navigator.openSubscription({
+              type: subscriptionType,
+              returnTo: "chat",
+              chatActionId: guidance.guidanceId,
+              analytics: {
+                entryPoint: "chat_input",
+                triggerReason: triggerReasonForGuidance(guidance.scene),
+              },
+            });
+          }}
+        >
+          <span>{guidance.ctaLabel}</span>
+          <ArrowRight size={17} aria-hidden="true" />
+        </button>
+      ) : null}
+    </aside>
+  );
+}

src/app/chat/hooks/use-chat-commercial-messages.ts

@@ -0,0 +1,38 @@
+"use client";
+
+import { useEffect } from "react";
+
+import { createChatWebSocket } from "@/core/net/chat-websocket";
+import type { LoginStatus } from "@/data/schemas/auth";
+import { getSessionAccessToken } from "@/lib/auth/auth_session";
+import { useChatDispatch } from "@/stores/chat/chat-context";
+
+export function useChatCommercialMessages(input: {
+  characterId: string;
+  loginStatus: LoginStatus;
+}) {
+  const chatDispatch = useChatDispatch();
+
+  useEffect(() => {
+    if (input.loginStatus === "notLoggedIn" || input.loginStatus === "guest") {
+      return;
+    }
+
+    let disposed = false;
+    let socket: ReturnType<typeof createChatWebSocket> | null = null;
+    void getSessionAccessToken().then((token) => {
+      if (disposed || !token) return;
+      socket = createChatWebSocket(token);
+      socket.onCommercialMessage = (message) => {
+        if (message.characterId !== input.characterId) return;
+        chatDispatch({ type: "ChatCommercialMessageReceived", message });
+      };
+      socket.connect();
+    });
+
+    return () => {
+      disposed = true;
+      socket?.disconnect();
+    };
+  }, [chatDispatch, input.characterId, input.loginStatus]);
+}

src/app/chat/hooks/use-chat-message-limit-banner.ts

@@ -5,6 +5,9 @@ import { useEffect, useRef } from "react";
 import { behaviorAnalytics } from "@/lib/analytics";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import type { ChatUpgradeReason } from "@/stores/chat/chat-state";
+import type { PaymentGuidance } from "@/data/schemas/chat";
+import { recordChatActionEventById } from "@/lib/chat/chat_action_events";
+import { useActiveCharacter } from "@/providers/character-provider";
 import { useUserSelector } from "@/stores/user/user-context";
 
 import {
@@ -17,10 +20,14 @@ import {
 export interface UseChatMessageLimitBannerInput {
   upgradePromptVisible: boolean;
   upgradeReason: ChatUpgradeReason | null;
+  paymentGuidance: PaymentGuidance | null;
 }
 
-export interface ChatMessageLimitBannerView
+export interface ChatMessageLimitBannerView {
-  extends InsufficientCreditsMessageLimitView {
+  title: string;
+  description: string;
+  ctaLabel: string | null;
+  guidance: PaymentGuidance | null;
   visible: boolean;
   unlock: () => void;
 }
@@ -28,10 +35,19 @@ export interface ChatMessageLimitBannerView
 export function useChatMessageLimitBanner({
   upgradePromptVisible,
   upgradeReason,
+  paymentGuidance,
 }: UseChatMessageLimitBannerInput): ChatMessageLimitBannerView {
   const navigator = useAppNavigator();
+  const character = useActiveCharacter();
   const isVip = useUserSelector((state) => state.context.isVip);
-  const view = getInsufficientCreditsMessageLimitView();
+  const fallbackView = getInsufficientCreditsMessageLimitView();
+  const guidance =
+    paymentGuidance?.characterId === character.id ? paymentGuidance : null;
+  const view: InsufficientCreditsMessageLimitView = {
+    title: guidance?.title ?? fallbackView.title,
+    description: guidance?.copy ?? fallbackView.description,
+    ctaLabel: guidance?.ctaLabel ?? fallbackView.ctaLabel,
+  };
   const visible = shouldShowMessageLimitBanner({
     upgradePromptVisible,
     upgradeReason,
@@ -52,12 +68,31 @@ export function useChatMessageLimitBanner({
       },
       { isVip },
     );
-  }, [isVip, visible]);
+    if (guidance) {
+      void recordChatActionEventById(
+        guidance.guidanceId,
+        character.id,
+        "viewed",
+      ).catch(() => undefined);
+    }
+  }, [character.id, guidance, isVip, visible]);
 
   function unlock(): void {
+    if (guidance?.mode !== "guide" && guidance !== null) return;
+    if (guidance) {
+      void recordChatActionEventById(
+        guidance.guidanceId,
+        character.id,
+        "opened",
+      ).catch(() => undefined);
+    }
     navigator.openSubscription({
-      type: getInsufficientCreditsSubscriptionType(isVip),
+      type:
+        isVip || (guidance && !guidance.purchaseOptions.includes("vip"))
+          ? "topup"
+          : getInsufficientCreditsSubscriptionType(isVip),
       returnTo: "chat",
+      ...(guidance ? { chatActionId: guidance.guidanceId } : {}),
       analytics: {
         entryPoint: "chat_input",
         triggerReason: "insufficient_credits",
@@ -67,6 +102,9 @@ export function useChatMessageLimitBanner({
 
   return {
     ...view,
+    ctaLabel:
+      guidance && guidance.mode !== "guide" ? null : view.ctaLabel,
+    guidance,
     visible,
     unlock,
   };

src/app/chat/hooks/use-chat-support-cta.ts

@@ -0,0 +1,97 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { shallowEqual } from "@xstate/react";
+
+import type { LoginStatus } from "@/data/schemas/auth";
+import { getDefaultPayChannelForCountryCode } from "@/lib/payment/default_pay_channel";
+import { useAppNavigator } from "@/router/use-app-navigator";
+import {
+  usePaymentDispatch,
+  usePaymentSelector,
+} from "@/stores/payment/payment-context";
+import { useUserSelector } from "@/stores/user/user-context";
+
+import { deriveChatSupportCta } from "../chat-support-cta";
+
+export function useChatSupportCta(input: {
+  characterId: string;
+  historyLoaded: boolean;
+  loginStatus: LoginStatus;
+}) {
+  const navigator = useAppNavigator();
+  const paymentDispatch = usePaymentDispatch();
+  const initializedCharacterRef = useRef<string | null>(null);
+  const [nowMs, setNowMs] = useState(() => Date.now());
+  const payment = usePaymentSelector(
+    (state) => ({
+      commercialOffer: state.context.commercialOffer,
+      isFirstRecharge: state.context.isFirstRecharge,
+      supportCharacterId: state.context.supportCharacterId,
+    }),
+    shallowEqual,
+  );
+  const countryCode = useUserSelector(
+    (state) => state.context.currentUser?.countryCode,
+  );
+  const isAuthenticated =
+    input.loginStatus !== "notLoggedIn" && input.loginStatus !== "guest";
+
+  useEffect(() => {
+    if (!isAuthenticated) return;
+    if (initializedCharacterRef.current === input.characterId) return;
+    initializedCharacterRef.current = input.characterId;
+    paymentDispatch({
+      type: "PaymentInit",
+      characterId: input.characterId,
+      payChannel: getDefaultPayChannelForCountryCode(countryCode),
+    });
+  }, [countryCode, input.characterId, isAuthenticated, paymentDispatch]);
+
+  useEffect(() => {
+    if (!payment.commercialOffer) return;
+    const timer = window.setInterval(() => setNowMs(Date.now()), 1000);
+    return () => window.clearInterval(timer);
+  }, [payment.commercialOffer]);
+
+  const cta = useMemo(
+    () =>
+      deriveChatSupportCta({
+        isFirstRecharge:
+          isAuthenticated && payment.supportCharacterId === input.characterId
+            ? payment.isFirstRecharge
+            : false,
+        commercialOffer:
+          isAuthenticated && payment.supportCharacterId === input.characterId
+            ? payment.commercialOffer
+            : null,
+        nowMs,
+      }),
+    [
+      input.characterId,
+      isAuthenticated,
+      nowMs,
+      payment.commercialOffer,
+      payment.isFirstRecharge,
+      payment.supportCharacterId,
+    ],
+  );
+
+  const open = () => {
+    navigator.openSubscription({
+      type: cta.planId?.startsWith("dol_") ? "topup" : "vip",
+      returnTo: "chat",
+      ...(cta.planId ? { planId: cta.planId } : {}),
+      ...(cta.commercialOfferId
+        ? { commercialOfferId: cta.commercialOfferId }
+        : {}),
+      analytics: {
+        entryPoint: "chat_offer_banner",
+        triggerReason:
+          cta.kind === "support" ? "vip_cta" : "commercial_offer",
+      },
+    });
+  };
+
+  return { ...cta, visible: input.historyLoaded, open };
+}

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

@@ -20,6 +20,7 @@ import {
 import type { ChatPromotionState } from "@/stores/chat/helper/promotion";
 import type { ChatUnlockPaywallRequest } from "@/stores/chat/chat-state";
 import type { UiMessage } from "@/stores/chat/ui-message";
+import { recordChatActionEventById } from "@/lib/chat/chat_action_events";
 import { useUserSelector } from "@/stores/user/user-context";
 
 import { getInsufficientCreditsSubscriptionType } from "../chat-screen.helpers";
@@ -48,6 +49,7 @@ export interface ChatUnlockDialogModel {
     lockedCount: number;
     isLoading: boolean;
     errorMessage: string | null;
+    guidance: import("@/data/schemas/chat").PaymentGuidance | null;
   };
   closeHistoryUnlock: () => void;
   confirmHistoryUnlock: () => void;
@@ -87,6 +89,8 @@ export function useChatUnlockCoordinator({
       isUnlockingHistory: state.matches({ userSession: "unlockingHistory" }),
       lockedHistoryCount: state.context.lockedHistoryCount,
       unlockHistoryError: state.context.unlockHistoryError,
+      unlockHistoryPaymentGuidance:
+        state.context.unlockHistoryPaymentGuidance,
       unlockHistoryPromptVisible: state.context.unlockHistoryPromptVisible,
       unlockPaywallRequest: state.context.unlockPaywallRequest,
     }),
@@ -97,6 +101,20 @@ export function useChatUnlockCoordinator({
     ? chatState.unlockPaywallRequest
     : null;
 
+  useEffect(() => {
+    const guidance = chatState.unlockHistoryPaymentGuidance;
+    if (!enabled || guidance?.characterId !== chatState.characterId) return;
+    void recordChatActionEventById(
+      guidance.guidanceId,
+      chatState.characterId,
+      "viewed",
+    ).catch(() => undefined);
+  }, [
+    chatState.characterId,
+    chatState.unlockHistoryPaymentGuidance,
+    enabled,
+  ]);
+
   useEffect(() => {
     if (!unlockPaywallRequest) {
       trackedPaywallRef.current = null;
@@ -120,7 +138,15 @@ export function useChatUnlockCoordinator({
       },
       { isVip },
     );
-  }, [isVip, unlockPaywallRequest]);
+    const guidance = unlockPaywallRequest.paymentGuidance;
+    if (guidance?.characterId === chatState.characterId) {
+      void recordChatActionEventById(
+        guidance.guidanceId,
+        chatState.characterId,
+        "viewed",
+      ).catch(() => undefined);
+    }
+  }, [chatState.characterId, isVip, unlockPaywallRequest]);
 
   useEffect(() => {
     if (!enabled) return;
@@ -212,6 +238,32 @@ export function useChatUnlockCoordinator({
   }
 
   function confirmHistoryUnlock(): void {
+    const guidance =
+      chatState.unlockHistoryPaymentGuidance?.characterId ===
+      chatState.characterId
+        ? chatState.unlockHistoryPaymentGuidance
+        : null;
+    if (guidance) {
+      if (guidance.mode !== "guide") return;
+      void recordChatActionEventById(
+        guidance.guidanceId,
+        chatState.characterId,
+        "opened",
+      ).catch(() => undefined);
+      navigator.openSubscription({
+        type:
+          isVip || !guidance.purchaseOptions.includes("vip")
+            ? "topup"
+            : "vip",
+        returnTo: "chat",
+        chatActionId: guidance.guidanceId,
+        analytics: {
+          entryPoint: "chat_unlock",
+          triggerReason: "insufficient_credits",
+        },
+      });
+      return;
+    }
     chatDispatch({ type: "ChatUnlockHistoryConfirmed" });
   }
 
@@ -221,6 +273,12 @@ export function useChatUnlockCoordinator({
 
   function confirmPaywall(): void {
     if (!unlockPaywallRequest) return;
+    const guidance =
+      unlockPaywallRequest.paymentGuidance?.characterId ===
+      chatState.characterId
+        ? unlockPaywallRequest.paymentGuidance
+        : null;
+    if (guidance && guidance.mode !== "guide") return;
 
     const returnUrl = resolveChatUnlockReturnUrl(
       unlockPaywallRequest,
@@ -231,6 +289,13 @@ export function useChatUnlockCoordinator({
       },
     );
     chatDispatch({ type: "ChatUnlockPaywallNavigationConsumed" });
+    if (guidance) {
+      void recordChatActionEventById(
+        guidance.guidanceId,
+        chatState.characterId,
+        "opened",
+      ).catch(() => undefined);
+    }
     navigator.openSubscriptionForPendingUnlock({
       displayMessageId: unlockPaywallRequest.displayMessageId,
       messageId: unlockPaywallRequest.messageId,
@@ -239,13 +304,17 @@ export function useChatUnlockCoordinator({
       clientLockId: unlockPaywallRequest.clientLockId,
       promotion: unlockPaywallRequest.promotion,
       returnUrl,
-      type: getInsufficientCreditsSubscriptionType(isVip),
+      type:
+        isVip || (guidance && !guidance.purchaseOptions.includes("vip"))
+          ? "topup"
+          : getInsufficientCreditsSubscriptionType(isVip),
       analytics: {
         entryPoint: "chat_unlock",
         triggerReason: unlockPaywallRequest.promotion
           ? "ad_landing"
           : "insufficient_credits",
       },
+      ...(guidance ? { chatActionId: guidance.guidanceId } : {}),
     });
   }
 
@@ -258,6 +327,7 @@ export function useChatUnlockCoordinator({
         lockedCount: chatState.lockedHistoryCount,
         isLoading: chatState.isUnlockingHistory,
         errorMessage: chatState.unlockHistoryError,
+        guidance: chatState.unlockHistoryPaymentGuidance,
       },
       closeHistoryUnlock,
       confirmHistoryUnlock,

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

@@ -21,6 +21,8 @@ import {
 } from "@/data/constants/character";
 import { Logger } from "@/utils/logger";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
+import { consumeTopUpHandoff } from "@/lib/auth/top_up_handoff";
+import { Result } from "@/utils/result";
 import {
   isFavoriteEntryRequest,
   persistFavoriteEntryIntent,
@@ -38,6 +40,7 @@ interface ExternalEntryPersistProps {
   mode: string | null;
   promotionType: string | null;
   favorite: string | null;
+  handoffToken: string | null;
 }
 
 export default function ExternalEntryPersist({
@@ -50,13 +53,16 @@ export default function ExternalEntryPersist({
   mode,
   promotionType,
   favorite,
+  handoffToken,
 }: ExternalEntryPersistProps) {
   const router = useRouter();
   const authState = useAuthState();
   const authDispatch = useAuthDispatch();
   const [hasPersisted, setHasPersisted] = useState(false);
+  const [handoffError, setHandoffError] = useState<string | null>(null);
+  const [handoffCompleted, setHandoffCompleted] = useState(false);
   const hasNavigatedRef = useRef(false);
-  const hasReinitializedForPsidRef = useRef(false);
+  const handoffStartedRef = useRef(false);
   const targetRoute = resolveExternalEntryTarget({ target });
   const destination = resolveExternalEntryDestination({ target, character });
   const characterId =
@@ -65,6 +71,12 @@ export default function ExternalEntryPersist({
     mode,
     promotionType,
   });
+  const isTopUpHandoff = targetRoute === ROUTES.subscription;
+  const displayedHandoffError =
+    handoffError ??
+    (isTopUpHandoff && !hasValue(handoffToken)
+      ? "This top-up link is invalid. Please request a new link in Messenger."
+      : null);
 
   useEffect(() => {
     let cancelled = false;
@@ -116,12 +128,39 @@ export default function ExternalEntryPersist({
   useEffect(() => {
     if (hasNavigatedRef.current || !hasPersisted) return;
 
-    // AuthStatusChecker can initialize before this entry has persisted PSID.
+    if (isTopUpHandoff) {
-    // Re-run the check so PSID direct login is not skipped by that race.
-    if (hasValue(psid) && !hasReinitializedForPsidRef.current) {
       if (!authState.hasInitialized || authState.isLoading) return;
-      hasReinitializedForPsidRef.current = true;
+      if (handoffCompleted) {
+        if (
+          authState.loginStatus === "notLoggedIn" ||
+          authState.loginStatus === "guest"
+        ) {
+          return;
+        }
+        hasNavigatedRef.current = true;
+        router.replace(destination);
+        return;
+      }
+      if (handoffStartedRef.current) return;
+      if (!hasValue(handoffToken)) return;
+      handoffStartedRef.current = true;
+      void (async () => {
+        const result = await consumeTopUpHandoff(handoffToken);
+        if (Result.isErr(result)) {
+          log.warn("[ExternalEntryPersist] top-up handoff failed", result.error);
+          window.history.replaceState(
+            window.history.state,
+            "",
+            "/external-entry?target=topup",
+          );
+          setHandoffError(
+            "This top-up link is invalid or has expired. Please request a new link in Messenger.",
+          );
+          return;
+        }
+        setHandoffCompleted(true);
         authDispatch({ type: "AuthInit" });
+      })();
       return;
     }
 
@@ -150,8 +189,12 @@ export default function ExternalEntryPersist({
     authState.hasInitialized,
     authState.isLoading,
     authState.loginStatus,
+    character,
     destination,
     hasPersisted,
+    handoffCompleted,
+    handoffToken,
+    isTopUpHandoff,
     psid,
     router,
   ]);
@@ -161,11 +204,26 @@ export default function ExternalEntryPersist({
       className="flex flex-1 items-center justify-center"
       style={{ minHeight: "100dvh" }}
     >
+      {displayedHandoffError ? (
+        <div className="mx-6 max-w-sm text-center">
+          <p className="text-sm text-[var(--color-text-secondary)]">
+            {displayedHandoffError}
+          </p>
+          <button
+            className="mt-5 rounded-full bg-[var(--color-accent)] px-5 py-2.5 text-sm font-semibold text-white"
+            type="button"
+            onClick={() => router.replace(ROUTES.root)}
+          >
+            Back to Cozsweet
+          </button>
+        </div>
+      ) : (
         <div
           aria-label="Redirecting"
           className="size-10 animate-spin rounded-full border-4 border-t-transparent"
           style={{ borderColor: "var(--color-accent)" }}
         />
+      )}
     </div>
   );
 }

src/app/external-entry/page.tsx

@@ -7,6 +7,7 @@
  * `/external-entry?target=chat&character=maya`
  * `/external-entry?target=tip`
  * `/external-entry?target=private-zone&character=nayeli`
+ * `/external-entry?target=topup&handoffToken=<opaque-token>`
  *
  * 页面不直接 `redirect()`，而是把数据交给 Client 组件先写入本地存储，
  * 再通过 `router.replace()` 清理 URL 并跳转到最终页面。
@@ -36,6 +37,7 @@ export default async function ExternalEntryPage({
       mode={pickParam(params.mode)}
       promotionType={pickParam(params.promotion_type)}
       favorite={pickParam(params.favorite)}
+      handoffToken={pickParam(params.handoffToken)}
     />
   );
 }

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

@@ -58,13 +58,13 @@ describe("Private Zone paywall navigation", () => {
     container.remove();
   });
 
-  it("opens top up with a private zone return target", () => {
+  it("opens VIP and credit options for a non-VIP user", () => {
     const roomDispatch = vi.fn<Dispatch<PrivateZoneEvent>>();
 
     renderHarness(root, "email", roomDispatch);
 
     expect(mocks.openSubscription).toHaveBeenCalledWith({
-      type: "topup",
+      type: "vip",
       returnTo: "private-zone",
       analytics: {
         entryPoint: "private_album_unlock",
@@ -115,6 +115,7 @@ function Harness({
     loginStatus,
     roomDispatch,
     unlockPaywallRequest,
+    isVip: false,
   });
   return null;
 }

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

@@ -19,6 +19,8 @@ import {
 } from "@/providers/character-provider";
 import { isPrivateAlbumLocked } from "@/lib/private-zone/private_album";
 import { behaviorAnalytics } from "@/lib/analytics";
+import { recordChatActionEventById } from "@/lib/chat/chat_action_events";
+import { useUserSelector } from "@/stores/user/user-context";
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
 import {
   usePrivateZoneDispatch,
@@ -63,7 +65,8 @@ export function PrivateZoneScreen() {
   const dispatch = usePrivateZoneDispatch();
   const postState = usePrivateZonePostState();
   const postDispatch = usePrivateZonePostDispatch();
-  const [activeTab, setActiveTab] = useState<"moments" | "albums">("moments");
+  const isVip = useUserSelector((user) => user.context.isVip);
+  const [activeTab, setActiveTab] = useState<"moments" | "albums">("albums");
   const openedGalleryInPageRef = useRef(false);
   const previousPostLoginStatusRef = useRef(authState.loginStatus);
   const galleryState = useMemo(
@@ -84,6 +87,7 @@ export function PrivateZoneScreen() {
     loginStatus: authState.loginStatus,
     roomDispatch: dispatch,
     unlockPaywallRequest: state.unlockPaywallRequest,
+    isVip,
   });
   usePrivateZoneUnlockSuccessRefresh(state.unlockSuccessNonce);
   usePrivateZoneUnlockSuccessRefresh(postState.unlockSuccessNonce);
@@ -119,9 +123,24 @@ export function PrivateZoneScreen() {
         entryPoint: "private_zone",
         triggerReason: "insufficient_credits",
       });
+      const guidance =
+        request.paymentGuidance?.characterId === character.id
+          ? request.paymentGuidance
+          : null;
+      if (guidance) {
+        void recordChatActionEventById(
+          guidance.guidanceId,
+          character.id,
+          "opened",
+        ).catch(() => undefined);
+      }
       navigator.openSubscription({
-        type: "topup",
+        type:
+          isVip || (guidance && !guidance.purchaseOptions.includes("vip"))
+            ? "topup"
+            : "vip",
         returnTo: "private-zone",
+        ...(guidance ? { chatActionId: guidance.guidanceId } : {}),
         analytics: {
           entryPoint: "private_zone",
           triggerReason: "insufficient_credits",
@@ -132,6 +151,8 @@ export function PrivateZoneScreen() {
   }, [
     authState.loginStatus,
     characterRoutes.privateZone,
+    character.id,
+    isVip,
     navigator,
     postDispatch,
     postState.unlockPaywallRequest,
@@ -205,7 +226,7 @@ export function PrivateZoneScreen() {
       return;
     }
     navigator.openSubscription({
-      type: "topup",
+      type: isVip ? "topup" : "vip",
       returnTo: "private-zone",
       analytics: {
         entryPoint: "private_zone",
@@ -313,15 +334,6 @@ export function PrivateZoneScreen() {
 
         <section className={styles.postsSection} aria-labelledby="posts-title">
           <div className={styles.contentTabs} role="tablist" aria-label="Private Zone content">
-            <button
-              type="button"
-              role="tab"
-              aria-selected={visibleTab === "moments"}
-              className={`${styles.contentTab} ${visibleTab === "moments" ? styles.contentTabActive : ""}`}
-              onClick={() => setActiveTab("moments")}
-            >
-              Moments
-            </button>
             <button
               type="button"
               role="tab"
@@ -331,6 +343,15 @@ export function PrivateZoneScreen() {
             >
               Albums
             </button>
+            <button
+              type="button"
+              role="tab"
+              aria-selected={visibleTab === "moments"}
+              className={`${styles.contentTab} ${visibleTab === "moments" ? styles.contentTabActive : ""}`}
+              onClick={() => setActiveTab("moments")}
+            >
+              Moments
+            </button>
           </div>
 
           <div className={styles.sectionHeader}>

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

@@ -5,12 +5,16 @@ import { type Dispatch, useEffect, useRef } from "react";
 import type { LoginStatus } from "@/data/schemas/auth";
 import { useGuestLoginBootstrap } from "@/hooks/use-guest-login-bootstrap";
 import { behaviorAnalytics } from "@/lib/analytics";
-import { useActiveCharacterRoutes } from "@/providers/character-provider";
+import {
+  useActiveCharacter,
+  useActiveCharacterRoutes,
+} from "@/providers/character-provider";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import type { AuthEvent } from "@/stores/auth/auth-events";
 import type { PrivateZoneEvent } from "@/stores/private-zone";
 import type { PrivateZoneUnlockPaywallRequest } from "@/stores/private-zone/private-zone-state";
 import { useUserDispatch } from "@/stores/user/user-context";
+import { recordChatActionEventById } from "@/lib/chat/chat_action_events";
 
 export interface UsePrivateZoneBootstrapFlowInput {
   authDispatch: Dispatch<AuthEvent>;
@@ -25,6 +29,7 @@ export interface UsePrivateZoneUnlockPaywallNavigationInput {
   loginStatus: LoginStatus;
   roomDispatch: Dispatch<PrivateZoneEvent>;
   unlockPaywallRequest: PrivateZoneUnlockPaywallRequest | null;
+  isVip: boolean;
 }
 
 export function isPrivateZoneAuthRequired(loginStatus: LoginStatus): boolean {
@@ -76,8 +81,10 @@ export function usePrivateZoneUnlockPaywallNavigation({
   loginStatus,
   roomDispatch,
   unlockPaywallRequest,
+  isVip,
 }: UsePrivateZoneUnlockPaywallNavigationInput): void {
   const navigator = useAppNavigator();
+  const character = useActiveCharacter();
   const characterRoutes = useActiveCharacterRoutes();
 
   useEffect(() => {
@@ -90,9 +97,26 @@ export function usePrivateZoneUnlockPaywallNavigation({
         entryPoint: "private_album_unlock",
         triggerReason: "insufficient_credits",
       });
+      const guidance = unlockPaywallRequest.paymentGuidance;
+      const activeGuidance =
+        guidance?.characterId === character.id ? guidance : null;
+      if (activeGuidance) {
+        void recordChatActionEventById(
+          activeGuidance.guidanceId,
+          activeGuidance.characterId,
+          "opened",
+        ).catch(() => undefined);
+      }
       navigator.openSubscription({
-        type: "topup",
+        type:
+          isVip ||
+          (activeGuidance && !activeGuidance.purchaseOptions.includes("vip"))
+            ? "topup"
+            : "vip",
         returnTo: "private-zone",
+        ...(activeGuidance
+          ? { chatActionId: activeGuidance.guidanceId }
+          : {}),
         analytics: {
           entryPoint: "private_album_unlock",
           triggerReason: "insufficient_credits",
@@ -102,7 +126,9 @@ export function usePrivateZoneUnlockPaywallNavigation({
     roomDispatch({ type: "PrivateZoneUnlockPaywallConsumed" });
   }, [
     characterRoutes.privateZone,
+    character.id,
     loginStatus,
+    isVip,
     navigator,
     roomDispatch,
     unlockPaywallRequest,

src/app/subscription/__tests__/subscription-page.test.tsx

@@ -34,14 +34,14 @@ describe("SubscriptionPage", () => {
     );
   });
 
-  it("uses Elio for missing source navigation context", async () => {
+  it("keeps the recipient empty when source navigation has no character", async () => {
     const page = await SubscriptionPage({
       searchParams: Promise.resolve({}),
     });
 
     renderToStaticMarkup(page);
     expect(mocks.screenProps).toHaveBeenLastCalledWith(
-      expect.objectContaining({ sourceCharacterSlug: "elio" }),
+      expect.objectContaining({ sourceCharacterSlug: null }),
     );
   });
 });

src/app/subscription/__tests__/subscription-screen-flow.test.tsx

@@ -3,6 +3,16 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => {
+  const characters = [
+    { id: "elio", slug: "elio", displayName: "Elio Silvestri", shortName: "Elio" },
+    { id: "maya-tan", slug: "maya", displayName: "Maya Tan", shortName: "Maya" },
+    {
+      id: "nayeli-cervantes",
+      slug: "nayeli",
+      displayName: "Nayeli Cervantes",
+      shortName: "Nayeli",
+    },
+  ];
   const payment = {
     status: "ready",
     plans: [
@@ -52,7 +62,17 @@ const mocks = vi.hoisted(() => {
       payment.selectedPlanId = event.planId;
     }
   });
-  return { payment, paymentDispatch, planClick: vi.fn() };
+  return {
+    characterCatalog: {
+      characters,
+      getBySlug: (slug: string | null) =>
+        characters.find((character) => character.slug === slug) ?? null,
+    },
+    payment,
+    paymentDispatch,
+    paymentFlowInput: vi.fn(),
+    planClick: vi.fn(),
+  };
 });
 
 vi.mock("@/app/_components", () => ({
@@ -83,6 +103,10 @@ vi.mock("@/stores/user/user-context", () => ({
   useUserState: () => ({ currentUser: { countryCode: "ID" } }),
 }));
 
+vi.mock("@/providers/character-catalog-provider", () => ({
+  useCharacterCatalog: () => mocks.characterCatalog,
+}));
+
 vi.mock("@/lib/payment/payment_method", () => ({
   getPaymentMethodConfig: () => ({
     initialPayChannel: "stripe",
@@ -97,13 +121,16 @@ vi.mock("@/lib/analytics", () => ({
 }));
 
 vi.mock("../use-subscription-payment-flow", () => ({
-  useSubscriptionPaymentFlow: () => ({
+  useSubscriptionPaymentFlow: (input: unknown) => {
+    mocks.paymentFlowInput(input);
+    return {
       payment: mocks.payment,
       paymentDispatch: mocks.paymentDispatch,
       showPaymentSuccessDialog: false,
       handleBackClick: vi.fn(),
       handlePaymentSuccessClose: vi.fn(),
-  }),
+    };
+  },
 }));
 
 vi.mock("../components", () => ({
@@ -170,8 +197,16 @@ describe("SubscriptionScreen payment selection flow", () => {
   beforeEach(() => {
     (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
       .IS_REACT_ACT_ENVIRONMENT = true;
+    mocks.payment.isFirstRecharge = false;
+    mocks.payment.commercialOffer = null;
+    for (const plan of mocks.payment.plans) {
+      delete (plan as Record<string, unknown>).isFirstRechargeOffer;
+      delete (plan as Record<string, unknown>).firstRechargeDiscountPercent;
+      delete (plan as Record<string, unknown>).promotionType;
+    }
     mocks.payment.selectedPlanId = "vip_monthly";
     mocks.paymentDispatch.mockClear();
+    mocks.paymentFlowInput.mockClear();
     mocks.planClick.mockClear();
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -184,7 +219,7 @@ describe("SubscriptionScreen payment selection flow", () => {
   });
 
   it("confirms VIP selection before enabling the separate checkout button", () => {
-    act(() => root.render(<SubscriptionScreen />));
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
     const checkout = container.querySelector<HTMLButtonElement>(
       '[data-testid="checkout"]',
     );
@@ -215,7 +250,7 @@ describe("SubscriptionScreen payment selection flow", () => {
   });
 
   it("keeps the original selection when VIP confirmation is cancelled", () => {
-    act(() => root.render(<SubscriptionScreen />));
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
     act(() => clickButton(container, "vip_quarterly"));
     expect(container.querySelector('[role="dialog"]')).not.toBeNull();
 
@@ -230,21 +265,21 @@ describe("SubscriptionScreen payment selection flow", () => {
   });
 
   it("requires VIP confirmation again after the page is remounted", () => {
-    act(() => root.render(<SubscriptionScreen />));
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
     act(() => clickButton(container, "vip_monthly"));
     act(() => clickButton(container, "Confirm"));
     expect(container.querySelector('[role="dialog"]')).toBeNull();
 
     act(() => root.unmount());
     root = createRoot(container);
-    act(() => root.render(<SubscriptionScreen />));
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
     act(() => clickButton(container, "vip_monthly"));
 
     expect(container.querySelector('[role="dialog"]')).not.toBeNull();
   });
 
   it("selects a coin package without showing the renewal dialog", () => {
-    act(() => root.render(<SubscriptionScreen />));
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
     act(() => clickButton(container, "coin_1000"));
 
     expect(container.querySelector('[role="dialog"]')).toBeNull();
@@ -256,6 +291,100 @@ describe("SubscriptionScreen payment selection flow", () => {
       expect.objectContaining({ type: "PaymentCreateOrderSubmitted" }),
     );
   });
+
+  it("keeps payment guidance bound to the source character", () => {
+    act(() =>
+      root.render(
+        <SubscriptionScreen
+          sourceCharacterSlug="maya"
+          chatActionId="019c8f8d-17d3-7a42-b1cc-b6927b1927d5"
+        />,
+      ),
+    );
+
+    const guidance = container.querySelector(
+      '[data-payment-guidance-character="maya-tan"]',
+    );
+    expect(guidance?.textContent).toContain("Keep talking with Maya");
+    expect(guidance?.textContent).toContain("support Maya");
+    expect(guidance?.textContent).toContain("cannot continue");
+    expect(guidance?.textContent).not.toContain("Elio");
+  });
+
+  it("does not render the first recharge banner on the subscription page", () => {
+    mocks.payment.isFirstRecharge = true;
+    Object.assign(mocks.payment.plans[0] as Record<string, unknown>, {
+      isFirstRechargeOffer: true,
+      firstRechargeDiscountPercent: 50,
+      promotionType: "first_recharge_half_price",
+    });
+
+    act(() => root.render(<SubscriptionScreen sourceCharacterSlug="elio" />));
+
+    expect(container.textContent).not.toContain("First Recharge Offer");
+    expect(container.textContent).not.toContain(
+      "Your first recharge price is already applied",
+    );
+  });
+
+  it.each(["elio", "maya", "nayeli"])(
+    "inherits the %s chat character without rendering a recipient selector",
+    (sourceCharacterSlug) => {
+      mocks.payment.selectedPlanId = "coin_1000";
+
+      act(() =>
+        root.render(
+          <SubscriptionScreen
+            subscriptionType="topup"
+            sourceCharacterSlug={sourceCharacterSlug}
+          />,
+        ),
+      );
+
+      const checkout = container.querySelector<HTMLButtonElement>(
+        '[data-testid="checkout"]',
+      );
+      expect(container.textContent).not.toContain("Supporting ");
+      expect(container.textContent).not.toContain(
+        "Choose who you want to support",
+      );
+      expect(container.textContent).not.toContain(
+        "Your VIP or credit purchase supports the character you choose",
+      );
+      expect(checkout?.disabled).toBe(false);
+      expect(mocks.paymentFlowInput).toHaveBeenLastCalledWith(
+        expect.objectContaining({ sourceCharacterSlug }),
+      );
+    },
+  );
+
+  it("does not invent a recipient when opened without a source character", () => {
+    mocks.payment.selectedPlanId = "coin_1000";
+
+    act(() =>
+      root.render(
+        <SubscriptionScreen
+          subscriptionType="topup"
+          sourceCharacterSlug={null}
+        />,
+      ),
+    );
+
+    const checkout = container.querySelector<HTMLButtonElement>(
+      '[data-testid="checkout"]',
+    );
+    expect(container.textContent).not.toContain("Supporting ");
+    expect(container.textContent).not.toContain(
+      "Choose who you want to support",
+    );
+    expect(container.textContent).not.toContain(
+      "Your VIP or credit purchase supports the character you choose",
+    );
+    expect(checkout?.disabled).toBe(true);
+    expect(mocks.paymentFlowInput).toHaveBeenLastCalledWith(
+      expect.objectContaining({ sourceCharacterSlug: null }),
+    );
+  });
 });
 
 function clickButton(root: ParentNode, label: string): void {

src/app/subscription/components/__tests__/subscription-payment-dialogs.test.tsx

@@ -3,8 +3,12 @@ import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { Result } from "@/utils/result";
+import { ApiError } from "@/data/services/api/api_result";
 
-import { SubscriptionPaymentIssueDialog } from "../subscription-payment-issue-dialog";
+import {
+  getPaymentIssueSubmitErrorLogDetails,
+  SubscriptionPaymentIssueDialog,
+} from "../subscription-payment-issue-dialog";
 import { SubscriptionRenewalConfirmationDialog } from "../subscription-renewal-confirmation-dialog";
 
 const mocks = vi.hoisted(() => ({
@@ -200,6 +204,28 @@ describe("subscription payment dialogs", () => {
     );
     expect(onClose).toHaveBeenCalledOnce();
   });
+
+  it("keeps HTTP status and backend error code in payment issue failure diagnostics", () => {
+    const failure = Result.err(
+      new ApiError("HTTP_ERROR", "Invalid feedback context", 400, {
+        detail: {
+          message: "Invalid feedback context",
+          errorCode: "INVALID_FEEDBACK_CONTEXT",
+        },
+      }),
+    );
+
+    if (failure.success) throw new Error("Expected failure result");
+    expect(getPaymentIssueSubmitErrorLogDetails(failure.error)).toMatchObject({
+      code: "UNKNOWN",
+      message: "Invalid feedback context",
+      causeName: "ApiError",
+      causeMessage: "Invalid feedback context",
+      httpStatus: 400,
+      apiCode: "HTTP_ERROR",
+      serverErrorCode: "INVALID_FEEDBACK_CONTEXT",
+    });
+  });
 });
 
 function clickButton(root: ParentNode | null, label: string): void {

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

@@ -1,7 +1,7 @@
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
 
-import { StripePaymentDialog } from "@/app/_components/payment/stripe-payment-dialog";
+import { stripePaymentDialogStyles } from "@/app/_components/payment/stripe-payment-dialog.styles";
 
 import { SubscriptionCtaButton } from "../subscription-cta-button";
 import { SubscriptionPaymentSuccessDialog } from "../subscription-payment-success-dialog";
@@ -48,19 +48,16 @@ describe("subscription Tailwind components", () => {
     expect(html).toContain("OK");
   });
 
-  it("renders StripePaymentDialog fallback with Tailwind dialog utilities", () => {
+  it("keeps Stripe dialog viewport and panel utilities", () => {
-    const html = renderToStaticMarkup(
+    expect(stripePaymentDialogStyles.overlay).toContain("fixed inset-0");
-      <StripePaymentDialog
+    expect(stripePaymentDialogStyles.dialog).toContain(
-        clientSecret="client-secret"
+      "max-w-(--dialog-wide-max-width,420px)",
-        onClose={() => undefined}
+    );
-      />,
+    expect(stripePaymentDialogStyles.dialog).toContain("overflow-y-auto");
+    expect(stripePaymentDialogStyles.dialog).toContain("overscroll-contain");
+    expect(stripePaymentDialogStyles.primary).toContain(
+      "bg-[linear-gradient(var(--color-button-gradient-start,#ff67e0)",
     );
-
-    expect(html).toContain('role="alertdialog"');
-    expect(html).toContain("fixed inset-0");
-    expect(html).toContain("max-w-(--dialog-wide-max-width,420px)");
-    expect(html).toContain("Payment unavailable");
-    expect(html).toContain("bg-[linear-gradient(var(--color-button-gradient-start,#ff67e0)");
   });
 
   it("renders most popular badges for VIP and coin plans", () => {

src/app/subscription/components/subscription-checkout-button.tsx

@@ -24,6 +24,7 @@ export interface SubscriptionCheckoutButtonProps {
   subscriptionType: "vip" | "topup";
   returnTo?: SubscriptionReturnTo;
   sourceCharacterSlug?: string;
+  countryCode?: string | null;
 }
 
 export function SubscriptionCheckoutButton({
@@ -31,6 +32,7 @@ export function SubscriptionCheckoutButton({
   subscriptionType,
   returnTo = null,
   sourceCharacterSlug = DEFAULT_CHARACTER_SLUG,
+  countryCode = null,
 }: SubscriptionCheckoutButtonProps) {
   const payment = usePaymentState();
   const paymentDispatch = usePaymentDispatch();
@@ -42,6 +44,7 @@ export function SubscriptionCheckoutButton({
     returnTo: returnTo ?? undefined,
     characterSlug: sourceCharacterSlug,
     subscriptionType,
+    countryCode,
   });
 
   const isLoading = payment.isCreatingOrder || payment.isPollingOrder;
@@ -57,7 +60,6 @@ export function SubscriptionCheckoutButton({
     paymentLaunch.resetLaunchState();
     paymentDispatch({ type: "PaymentCreateOrderSubmitted" });
   };
-
   return (
     <>
       <SubscriptionCtaButton
@@ -86,7 +88,7 @@ export function SubscriptionCheckoutButton({
       <PaymentLaunchDialogs
         currentOrderId={payment.currentOrderId}
         externalCheckoutAnalyticsKey="subscription.external_checkout"
-        ezpayDescription="Your order has been created. Continue to GCash to finish the payment."
+        ezpayDescription="Your order has been created. Continue to the secure payment page to finish."
         launch={paymentLaunch}
       />
     </>

src/app/subscription/components/subscription-payment-issue-dialog.tsx

@@ -6,6 +6,7 @@ import { ModalPortal } from "@/app/_components/core/modal-portal";
 import { createFeedbackContext } from "@/app/feedback/feedback-context";
 import type { PayChannel } from "@/data/schemas/payment";
 import { submitFeedback } from "@/lib/feedback";
+import { Logger } from "@/utils/logger";
 
 import type { SubscriptionType } from "../subscription-screen.helpers";
 import styles from "./subscription-dialog.module.css";
@@ -33,6 +34,21 @@ const OTHER_DETAILS_MIN_LENGTH = 10;
 const OTHER_DETAILS_MAX_LENGTH = 2000;
 const SUCCESS_MESSAGE = "Thanks. Your payment issue has been submitted.";
 const FAILURE_MESSAGE = "Unable to submit. Please try again.";
+const log = new Logger("SubscriptionPaymentIssueDialog");
+
+interface ErrorRecord {
+  readonly [key: string]: unknown;
+}
+
+export interface PaymentIssueSubmitErrorLogDetails {
+  code: string;
+  message: string;
+  causeName?: string;
+  causeMessage?: string;
+  httpStatus?: number;
+  apiCode?: string;
+  serverErrorCode?: string;
+}
 
 export interface SubscriptionPaymentIssueDialogProps {
   open: boolean;
@@ -119,6 +135,19 @@ export function SubscriptionPaymentIssueDialog({
     });
 
     if (!result.success) {
+      log.error(
+        {
+          ...getPaymentIssueSubmitErrorLogDetails(result.error),
+          paymentIssueReason: reason,
+          subscriptionType,
+          planId,
+          orderId,
+          payChannel,
+          countryCode,
+          characterId,
+        },
+        "Payment issue feedback submit failed",
+      );
       setErrorMessage(FAILURE_MESSAGE);
       setIsSubmitting(false);
       return;
@@ -206,6 +235,32 @@ export function SubscriptionPaymentIssueDialog({
   );
 }
 
+export function getPaymentIssueSubmitErrorLogDetails(
+  error: Error,
+): PaymentIssueSubmitErrorLogDetails {
+  const errorRecord = toErrorRecord(error);
+  const cause = toErrorRecord(errorRecord?.cause);
+  const responseDetails = toErrorRecord(cause?.details);
+  const detail = toErrorRecord(responseDetails?.detail);
+  const causeName = stringValue(cause?.name);
+  const causeMessage = stringValue(cause?.message);
+  const httpStatus = numberValue(cause?.status);
+  const apiCode = stringValue(cause?.code);
+  const serverErrorCode =
+    stringValue(detail?.errorCode) ??
+    stringValue(responseDetails?.errorCode);
+
+  return {
+    code: stringValue(errorRecord?.code) ?? "UNKNOWN",
+    message: error.message,
+    ...(causeName ? { causeName } : {}),
+    ...(causeMessage ? { causeMessage } : {}),
+    ...(httpStatus !== undefined ? { httpStatus } : {}),
+    ...(apiCode ? { apiCode } : {}),
+    ...(serverErrorCode ? { serverErrorCode } : {}),
+  };
+}
+
 function createIdempotencyKey(): string {
   const token =
     typeof crypto !== "undefined" && "randomUUID" in crypto
@@ -213,3 +268,18 @@ function createIdempotencyKey(): string {
       : `${Date.now()}_${Math.random().toString(36).slice(2)}`;
   return `payment_feedback_${token}`;
 }
+
+function toErrorRecord(value: unknown): ErrorRecord | null {
+  if (typeof value !== "object" || value === null) return null;
+  return value as ErrorRecord;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}

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

@@ -1,14 +1,24 @@
 .shell {
   display: flex;
   flex-direction: column;
+  height: var(--app-viewport-height, 100dvh);
   min-height: var(--app-viewport-height, 100dvh);
+  overflow: hidden;
   background:
     radial-gradient(circle at 8% 4%, rgba(255, 255, 255, 0.95) 0 90px, transparent 160px),
     linear-gradient(180deg, #fff9fb 0%, #fcf3f4 52%, #fffefe 100%);
+}
+
+.scrollArea {
+  min-height: 0;
+  flex: 1 1 auto;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: contain;
   padding:
     calc(var(--page-padding-y, 18px) + var(--app-safe-top, 0px))
     calc(var(--page-padding-x, 20px) + var(--app-safe-right, 0px))
-    calc(104px + var(--app-safe-bottom, 0px))
+    var(--page-section-gap-lg, 22px)
     calc(var(--page-padding-x, 20px) + var(--app-safe-left, 0px));
 }
 
@@ -61,6 +71,29 @@
   box-shadow: 0 12px 30px rgba(22, 101, 52, 0.12);
 }
 
+.characterSupportBanner {
+  margin-top: var(--page-section-gap, 14px);
+  padding: 14px 16px;
+  border: 1px solid rgba(246, 87, 160, 0.2);
+  border-radius: var(--responsive-card-radius-sm, 22px);
+  background: rgba(255, 255, 255, 0.9);
+  color: #4a3340;
+  box-shadow: 0 10px 24px rgba(246, 87, 160, 0.1);
+}
+
+.characterSupportBanner h2 {
+  margin: 0;
+  color: #24151d;
+  font-size: var(--responsive-card-title, 17px);
+  line-height: 1.25;
+}
+
+.characterSupportBanner p {
+  margin: 6px 0 0;
+  font-size: var(--responsive-caption, 14px);
+  line-height: 1.45;
+}
+
 .firstRechargeBanner {
   display: flex;
   align-items: center;
@@ -168,11 +201,12 @@
 }
 
 .ctaSlot {
-  position: fixed;
+  position: relative;
   z-index: 40;
-  right: 50%;
+  flex: 0 0 auto;
-  bottom: 0;
+  width: 100%;
-  width: min(100%, var(--app-max-width, 540px));
+  max-height: min(50dvh, 360px);
+  overflow-y: auto;
   padding:
     12px
     calc(var(--page-padding-x, 20px) + var(--app-safe-right, 0px))
@@ -186,5 +220,4 @@
   );
   box-shadow: 0 -12px 30px rgba(87, 35, 59, 0.1);
   backdrop-filter: blur(16px);
-  transform: translateX(50%);
 }

src/app/subscription/page.tsx

@@ -10,7 +10,6 @@ import {
   type PaymentSearchParams,
 } from "@/lib/payment/payment_search_params";
 import {
-  DEFAULT_CHARACTER_SLUG,
   getCharacterBySlug,
 } from "@/data/constants/character";
 
@@ -30,8 +29,7 @@ export default async function SubscriptionPage({
     getFirstPaymentSearchParam(query.type),
   );
   const sourceCharacterSlug =
-    getCharacterBySlug(getFirstPaymentSearchParam(query.character))?.slug ??
+    getCharacterBySlug(getFirstPaymentSearchParam(query.character))?.slug ?? null;
-    DEFAULT_CHARACTER_SLUG;
   const initialPlanId = getFirstPaymentSearchParam(query.planId);
   const commercialOfferId = getFirstPaymentSearchParam(
     query.commercialOfferId,

src/app/subscription/subscription-screen.tsx

@@ -9,12 +9,14 @@ import { usePaymentPlanAnalytics } from "@/app/_hooks/use-payment-plan-analytics
 import type { PayChannel } from "@/data/schemas/payment";
 import type { SubscriptionReturnTo } from "@/lib/navigation/subscription_exit";
 import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
+import { useCharacterCatalog } from "@/providers/character-catalog-provider";
 import {
   behaviorAnalytics,
   getDefaultPaymentAnalyticsContext,
   type PaymentAnalyticsContext,
 } from "@/lib/analytics";
 import { getPaymentMethodConfig } from "@/lib/payment/payment_method";
+import { useHasHydrated } from "@/hooks/use-has-hydrated";
 import { useUserState } from "@/stores/user/user-context";
 
 import {
@@ -46,7 +48,7 @@ export interface SubscriptionScreenProps {
   returnTo?: SubscriptionReturnTo;
   initialPayChannel?: PayChannel | null;
   analyticsContext?: PaymentAnalyticsContext;
-  sourceCharacterSlug?: string;
+  sourceCharacterSlug?: string | null;
   initialPlanId?: string | null;
   commercialOfferId?: string | null;
   resumeOrderId?: string | null;
@@ -59,7 +61,7 @@ export function SubscriptionScreen({
   returnTo = null,
   initialPayChannel = null,
   analyticsContext: providedAnalyticsContext,
-  sourceCharacterSlug = DEFAULT_CHARACTER_SLUG,
+  sourceCharacterSlug = null,
   initialPlanId = null,
   commercialOfferId = null,
   resumeOrderId = null,
@@ -73,12 +75,18 @@ export function SubscriptionScreen({
   const [paymentIssueNotice, setPaymentIssueNotice] = useState<string | null>(
     null,
   );
+  const characterCatalog = useCharacterCatalog();
   const userState = useUserState();
+  const sourceCharacter = characterCatalog.getBySlug(sourceCharacterSlug);
+  const hasHydrated = useHasHydrated();
   const countryCode = userState.currentUser?.countryCode;
   const paymentMethodConfig = getPaymentMethodConfig({
     countryCode,
     requestedPayChannel: initialPayChannel,
   });
+  const renderedPaymentMethodConfig = hasHydrated
+    ? paymentMethodConfig
+    : { ...paymentMethodConfig, showPaymentMethodSelector: false };
   const {
     payment,
     paymentDispatch,
@@ -89,7 +97,7 @@ export function SubscriptionScreen({
     subscriptionType,
     shouldResumePendingOrder,
     returnTo,
-    sourceCharacterSlug,
+    sourceCharacterSlug: sourceCharacter?.slug ?? null,
     initialPayChannel: paymentMethodConfig.initialPayChannel,
     initialPlanId,
     commercialOfferId,
@@ -120,14 +128,14 @@ export function SubscriptionScreen({
     });
   }, [canSubscribeVip, directCoinsPlans, payment.plans, vipOfferPlans]);
   usePaymentPlanAnalytics(displayedPlans, analyticsContext);
-  const firstRechargeOffer = useMemo(
+  const hasFirstRechargeOffer = useMemo(
     () =>
       getFirstRechargeOfferView({
         isFirstRecharge: payment.isFirstRecharge,
         subscriptionType,
         vipPlans: vipOfferPlans,
         coinPlans: directCoinsPlans,
-      }),
+      }) !== null,
     [
       directCoinsPlans,
       payment.isFirstRecharge,
@@ -149,6 +157,7 @@ export function SubscriptionScreen({
     (plan) => plan.id === payment.selectedPlanId,
   );
   const canActivate =
+    sourceCharacter !== null &&
     selectedPlan !== null &&
     canCheckoutSubscriptionPlan({
       selectedPlanId: payment.selectedPlanId,
@@ -232,6 +241,7 @@ export function SubscriptionScreen({
   return (
     <MobileShell>
       <div className={styles.shell}>
+        <div className={styles.scrollArea}>
           <header className={styles.header}>
           <BackButton
             className={styles.backSlot}
@@ -257,38 +267,32 @@ export function SubscriptionScreen({
           </p>
         ) : null}
 
-        {firstRechargeOffer ? (
+        {chatActionId && sourceCharacter ? (
           <section
-            className={styles.firstRechargeBanner}
+            className={styles.characterSupportBanner}
-            aria-label="First recharge offer"
+            aria-label={`Support ${sourceCharacter.displayName}`}
+            data-payment-guidance-character={sourceCharacter.id}
           >
-            <span className={styles.firstRechargeBadge}>
+            <h2>Keep talking with {sourceCharacter.shortName}</h2>
-              {firstRechargeOffer.badgeText}
+            <p>
-            </span>
+              Without the required VIP access or credits, paid chat and locked
-            <div className={styles.firstRechargeCopy}>
+              content cannot continue. Choosing an option here is a voluntary
-              <h2 className={styles.firstRechargeTitle}>
+              way to support{" "}
-                {firstRechargeOffer.title}
+              {sourceCharacter.shortName}; it is never a test of your feelings.
-              </h2>
-              <p className={styles.firstRechargeSubtitle}>
-                {firstRechargeOffer.subtitle}
             </p>
-              {firstRechargeOffer.renewalNotice ? (
-                <p className={styles.firstRechargeRenewalNotice}>
-                  {firstRechargeOffer.renewalNotice}
-                </p>
-              ) : null}
-            </div>
           </section>
         ) : null}
 
-        {payment.commercialOffer && !firstRechargeOffer ? (
+        {payment.commercialOffer && !hasFirstRechargeOffer && sourceCharacter ? (
           <section
             className={styles.firstRechargeBanner}
-            aria-label="Elio private offer"
+            aria-label={`${sourceCharacter.shortName} private offer`}
           >
             <span className={styles.firstRechargeBadge}>Private offer</span>
             <div className={styles.firstRechargeCopy}>
-              <h2 className={styles.firstRechargeTitle}>Elio got this price for you</h2>
+              <h2 className={styles.firstRechargeTitle}>
+                {sourceCharacter.shortName} got this price for you
+              </h2>
               <p className={styles.firstRechargeSubtitle}>
                 {payment.commercialOffer.message ||
                   `Your ${payment.commercialOffer.discountPercent}% discount is already applied below.`}
@@ -313,21 +317,27 @@ export function SubscriptionScreen({
         </div>
 
           <PaymentMethodSelector
-          config={paymentMethodConfig}
+            config={renderedPaymentMethodConfig}
             value={payment.payChannel}
-          disabled={isPaymentBusy}
+            disabled={payment.isCreatingOrder}
-          caption="GCash by default in the Philippines"
+            caption={
+              paymentMethodConfig.ezpayDisplayName === "QRIS"
+                ? "QRIS by default in Indonesia"
+                : "GCash by default in the Philippines"
+            }
             className={styles.paymentMethodSlot}
             analyticsKey="subscription.payment_method"
             onChange={handlePaymentMethodChange}
           />
+        </div>
 
         <div className={styles.ctaSlot}>
           <SubscriptionCheckoutButton
             disabled={!canActivate}
             subscriptionType={subscriptionType}
             returnTo={returnTo}
-            sourceCharacterSlug={sourceCharacterSlug}
+            sourceCharacterSlug={sourceCharacter?.slug ?? DEFAULT_CHARACTER_SLUG}
+            countryCode={countryCode}
           />
         </div>
 
@@ -352,7 +362,7 @@ export function SubscriptionScreen({
             orderId={payment.currentOrderId}
             payChannel={payment.payChannel}
             countryCode={countryCode}
-            characterId={sourceCharacterSlug}
+            characterId={sourceCharacter?.id ?? ""}
             onClose={() => setShowPaymentIssueDialog(false)}
             onSubmitted={setPaymentIssueNotice}
           />

src/app/subscription/use-subscription-payment-flow.ts

@@ -5,7 +5,10 @@ import { useRouter } from "next/navigation";
 
 import { usePaymentRouteFlow } from "@/app/_hooks/use-payment-route-flow";
 import type { PayChannel } from "@/data/schemas/payment";
-import { DEFAULT_CHARACTER_SLUG } from "@/data/constants/character";
+import {
+  DEFAULT_CHARACTER,
+  getCharacterBySlug,
+} from "@/data/constants/character";
 import {
   consumeSubscriptionExitUrl,
   resolveSubscriptionSuccessExitUrl,
@@ -19,7 +22,7 @@ export interface UseSubscriptionPaymentFlowInput {
   shouldResumePendingOrder: boolean;
   returnTo: SubscriptionReturnTo;
   initialPayChannel: PayChannel;
-  sourceCharacterSlug?: string;
+  sourceCharacterSlug?: string | null;
   initialPlanId?: string | null;
   commercialOfferId?: string | null;
   resumeOrderId?: string | null;
@@ -31,17 +34,20 @@ export function useSubscriptionPaymentFlow({
   shouldResumePendingOrder,
   returnTo,
   initialPayChannel,
-  sourceCharacterSlug = DEFAULT_CHARACTER_SLUG,
+  sourceCharacterSlug = null,
   initialPlanId = null,
   commercialOfferId = null,
   resumeOrderId = null,
   chatActionId = null,
 }: UseSubscriptionPaymentFlowInput) {
   const router = useRouter();
+  const supportCharacter = getCharacterBySlug(sourceCharacterSlug);
+  const exitCharacterSlug = supportCharacter?.slug ?? DEFAULT_CHARACTER.slug;
   const { payment, paymentDispatch } = usePaymentRouteFlow({
     initialPayChannel,
     paymentType: subscriptionType,
     shouldResumePendingOrder,
+    characterId: supportCharacter?.id,
     initialPlanId,
     commercialOfferId,
     resumeOrderId,
@@ -62,7 +68,7 @@ export function useSubscriptionPaymentFlow({
   const handleBackClick = () => {
     void (async () => {
       router.replace(
-        await consumeSubscriptionExitUrl(returnTo, sourceCharacterSlug),
+        await consumeSubscriptionExitUrl(returnTo, exitCharacterSlug),
       );
     })();
   };
@@ -74,7 +80,7 @@ export function useSubscriptionPaymentFlow({
       router.replace(
         await resolveSubscriptionSuccessExitUrl(
           returnTo,
-          sourceCharacterSlug,
+          exitCharacterSlug,
         ),
       );
     })();

src/app/tip/tip-checkout-button.tsx

@@ -19,6 +19,7 @@ export interface TipCheckoutButtonProps {
   disabled?: boolean;
   onOrder: () => void;
   returnPath: string;
+  countryCode?: string | null;
 }
 
 export function TipCheckoutButton({
@@ -27,6 +28,7 @@ export function TipCheckoutButton({
   disabled = false,
   onOrder,
   returnPath,
+  countryCode = null,
 }: TipCheckoutButtonProps) {
   const character = useActiveCharacter();
   const payment = usePaymentState();
@@ -40,6 +42,7 @@ export function TipCheckoutButton({
     giftCategory,
     giftPlanId,
     characterSlug: character.slug,
+    countryCode,
   });
 
   const isLoading = payment.isCreatingOrder || payment.isPollingOrder;
@@ -71,7 +74,7 @@ export function TipCheckoutButton({
       <PaymentLaunchDialogs
         currentOrderId={payment.currentOrderId}
         externalCheckoutAnalyticsKey="tip.external_checkout"
-        ezpayDescription="Your coffee order is ready. Continue to GCash to finish the payment."
+        ezpayDescription="Your gift order is ready. Continue to the secure payment page to finish."
         launch={paymentLaunch}
         stripeReturnPath={returnPath}
       />

src/app/tip/tip-screen.tsx

@@ -14,6 +14,7 @@ import {
   type PaymentAnalyticsContext,
 } from "@/lib/analytics";
 import { getPaymentMethodConfig } from "@/lib/payment/payment_method";
+import { useHasHydrated } from "@/hooks/use-has-hydrated";
 import { buildTipGiftPath } from "@/lib/tip/tip_gift";
 import {
   useActiveCharacter,
@@ -52,11 +53,15 @@ export function TipScreen({
   const character = useActiveCharacter();
   const characterRoutes = useActiveCharacterRoutes();
   const userState = useUserState();
-  const supportPrompt = useTipSupportPrompt();
+  const hasHydrated = useHasHydrated();
+  const supportPrompt = useTipSupportPrompt(character.displayName);
   const paymentMethodConfig = getPaymentMethodConfig({
     countryCode: userState.currentUser?.countryCode,
     requestedPayChannel: initialPayChannel,
   });
+  const renderedPaymentMethodConfig = hasHydrated
+    ? paymentMethodConfig
+    : { ...paymentMethodConfig, showPaymentMethodSelector: false };
   const { payment, paymentDispatch } = usePaymentRouteFlow({
     catalog: "tip",
     characterId: character.id,
@@ -284,10 +289,10 @@ export function TipScreen({
                 </section>
 
                 <PaymentMethodSelector
-                  config={paymentMethodConfig}
+                  config={renderedPaymentMethodConfig}
                   value={payment.payChannel}
                   density="compact"
-                  disabled={isPaymentBusy}
+                  disabled={payment.isCreatingOrder}
                   className={styles.paymentMethodSlot}
                   analyticsKey="tip.payment_method"
                   onChange={handlePaymentMethodChange}
@@ -300,6 +305,7 @@ export function TipScreen({
                     disabled={!canCreateOrder}
                     onOrder={handleOrder}
                     returnPath={returnPath}
+                    countryCode={userState.currentUser?.countryCode}
                   />
                 </div>
               </>

src/app/tip/use-tip-support-prompt.ts

@@ -15,22 +15,30 @@ export interface TipSupportPromptState {
   readonly isReady: boolean;
 }
 
-export function useTipSupportPrompt(): TipSupportPromptState {
+export function useTipSupportPrompt(
+  characterName = "this character",
+): TipSupportPromptState {
   const [selection, setSelection] =
     useState<ReturnType<typeof selectTipSupportPrompt> | null>(null);
 
   useEffect(() => {
     const frameId = requestAnimationFrame(() => {
-      const nextSelection = selectTipSupportPrompt(readPreviousIndex());
+      const nextSelection = selectTipSupportPrompt(
+        readPreviousIndex(),
+        Math.random,
+        characterName,
+      );
       writePreviousIndex(nextSelection.index);
       setSelection(nextSelection);
     });
 
     return () => cancelAnimationFrame(frameId);
-  }, []);
+  }, [characterName]);
 
   return {
-    prompt: selection?.prompt ?? TIP_SUPPORT_PROMPTS[0],
+    prompt:
+      selection?.prompt ??
+      TIP_SUPPORT_PROMPTS[0].replaceAll("this character", characterName),
     isReady: selection !== null,
   };
 }

src/core/net/__tests__/chat-websocket-payment-guidance.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { ChatWebSocket } from "../chat-websocket";
+
+describe("ChatWebSocket payment guidance", () => {
+  it("parses the same role-bound decision emitted by HTTP", () => {
+    const socket = new ChatWebSocket("ws://example.test/chat", "token");
+    const onPaymentGuidance = vi.fn();
+    socket.onPaymentGuidance = onPaymentGuidance;
+
+    receive(socket, {
+      type: "payment_guidance",
+      data: {
+        guidanceId: "019c8f8d-17d3-7a42-b1cc-b6927b1927d5",
+        characterId: "maya-tan",
+        characterName: "Maya Tan",
+        scene: "voiceLocked",
+        mode: "guide",
+        title: "Keep talking with Maya",
+        copy: "Hey love, I want to keep talking with you.",
+        ctaLabel: "View VIP & credit options",
+        purchaseOptions: ["vip", "topup"],
+        target: "subscription",
+        ruleId: "payment_guidance_voiceLocked",
+      },
+    });
+
+    expect(onPaymentGuidance).toHaveBeenCalledWith(
+      expect.objectContaining({
+        characterId: "maya-tan",
+        scene: "voiceLocked",
+      }),
+    );
+  });
+
+  it("ignores malformed guidance instead of rendering the wrong role", () => {
+    const socket = new ChatWebSocket("ws://example.test/chat", "token");
+    const onPaymentGuidance = vi.fn();
+    socket.onPaymentGuidance = onPaymentGuidance;
+
+    receive(socket, {
+      type: "payment_guidance",
+      data: { characterId: "elio" },
+    });
+
+    expect(onPaymentGuidance).not.toHaveBeenCalled();
+  });
+
+  it("delivers a persisted commercial thank-you as a live role message", () => {
+    const socket = new ChatWebSocket("ws://example.test/chat", "token");
+    const onCommercialMessage = vi.fn();
+    socket.onCommercialMessage = onCommercialMessage;
+
+    receive(socket, {
+      type: "commercial_message",
+      messageId: "message-1",
+      message: "Thank you for supporting me.",
+      characterId: "maya-tan",
+      createdAt: "2026-07-28T00:00:00.000Z",
+    });
+
+    expect(onCommercialMessage).toHaveBeenCalledWith({
+      messageId: "message-1",
+      message: "Thank you for supporting me.",
+      characterId: "maya-tan",
+      createdAt: "2026-07-28T00:00:00.000Z",
+    });
+  });
+});
+
+function receive(socket: ChatWebSocket, payload: unknown): void {
+  (
+    socket as unknown as { handleMessage: (data: string) => void }
+  ).handleMessage(JSON.stringify(payload));
+}

src/core/net/chat-websocket.ts

@@ -15,8 +15,10 @@ import { Logger } from "@/utils/logger";
 import {
   CommercialActionSchema,
   ChatActionSchema,
+  PaymentGuidanceSchema,
   type ChatAction,
   type CommercialAction,
+  type PaymentGuidance,
 } from "@/data/schemas/chat";
 import { createClientMessageId } from "@/lib/chat/client_message_id";
 
@@ -35,6 +37,13 @@ export interface PaywallStatusPayload {
   reason: string | null;
 }
 
+export interface CommercialMessagePayload {
+  messageId: string;
+  message: string;
+  characterId: string;
+  createdAt: string;
+}
+
 export class ChatWebSocket {
   private ws: WebSocket | null = null;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
@@ -49,6 +58,8 @@ export class ChatWebSocket {
   onPaywallStatus: ((payload: PaywallStatusPayload) => void) | null = null;
   onCommercialAction: ((action: CommercialAction) => void) | null = null;
   onChatAction: ((action: ChatAction) => void) | null = null;
+  onPaymentGuidance: ((guidance: PaymentGuidance) => void) | null = null;
+  onCommercialMessage: ((message: CommercialMessagePayload) => void) | null = null;
   onError: ((errorMessage: string) => void) | null = null;
 
   constructor(
@@ -146,7 +157,11 @@ export class ChatWebSocket {
       done?: boolean;
       audioUrl?: string;
       error?: string;
-      data?: {
+      messageId?: string;
+      message?: string;
+      characterId?: string;
+      createdAt?: string;
+      data?: Record<string, unknown> & {
         image?: {
           type?: string | null;
           url?: string | null;
@@ -160,6 +175,10 @@ export class ChatWebSocket {
         ruleId?: string;
         kind?: string;
         orderId?: string | null;
+        messageId?: string;
+        message?: string;
+        characterId?: string;
+        createdAt?: string;
       };
     };
     try {
@@ -209,6 +228,30 @@ export class ChatWebSocket {
         if (action.success) this.onChatAction?.(action.data);
         break;
       }
+      case "payment_guidance": {
+        const guidance = PaymentGuidanceSchema.safeParse(payload.data);
+        if (guidance.success) this.onPaymentGuidance?.(guidance.data);
+        break;
+      }
+      case "commercial_message": {
+        const commercialMessage = payload.data?.messageId
+          ? payload.data
+          : payload;
+        if (
+          commercialMessage?.messageId &&
+          commercialMessage.message &&
+          commercialMessage.characterId &&
+          commercialMessage.createdAt
+        ) {
+          this.onCommercialMessage?.({
+            messageId: commercialMessage.messageId,
+            message: commercialMessage.message,
+            characterId: commercialMessage.characterId,
+            createdAt: commercialMessage.createdAt,
+          });
+        }
+        break;
+      }
       case "error":
         this.onError?.(payload.error ?? "Unknown error");
         break;

src/data/repositories/__tests__/auth_repository.facebook_identity.test.ts

@@ -3,8 +3,6 @@ import { describe, expect, it, vi } from "vitest";
 import { AuthRepository } from "@/data/repositories/auth_repository";
 import {
   FacebookIdentityResponseSchema,
-  FacebookPsidLoginResponseSchema,
-  LoginStatus,
 } from "@/data/schemas/auth";
 import type { AuthApi } from "@/data/services/api";
 import type { IAuthStorage } from "@/data/storage/auth";
@@ -54,85 +52,4 @@ describe("AuthRepository facebook identity", () => {
     expect(storage.setAsid).toHaveBeenCalledWith("asid-1");
     expect(storage.setPsid).toHaveBeenCalledWith("psid-1");
   });
-
-  it("saves real login data from complete psid login responses", async () => {
-    const facebookPsidLogin = vi.fn(async () =>
-      FacebookPsidLoginResponseSchema.parse({
-        token: "login-token",
-        refreshToken: "refresh-token",
-        matchedBy: "psid",
-        fbAsid: "asid-1",
-        fbPsid: "psid-1",
-        hasCompleteFacebookIdentity: true,
-        isGuest: false,
-        user: { id: "user-1", username: "Elio" },
-      }),
-    );
-    const { repository, storage, userStorage } = createRepository({
-      facebookPsidLogin,
-    });
-
-    const result = await repository.facebookPsidLogin({
-      psid: "psid-1",
-      deviceId: "device-1",
-    });
-
-    expect(result).toEqual(Result.ok(LoginStatus.Facebook));
-    expect(storage.setLoginToken).toHaveBeenCalledWith("login-token");
-    expect(storage.setRefreshToken).toHaveBeenCalledWith("refresh-token");
-    expect(storage.setLoginProvider).toHaveBeenCalledWith(LoginStatus.Facebook);
-    expect(userStorage.setUserId).toHaveBeenCalledWith("user-1");
-    expect(storage.setAsid).toHaveBeenCalledWith("asid-1");
-    expect(storage.setPsid).toHaveBeenCalledWith("psid-1");
-  });
-
-  it("saves guest data from incomplete psid login responses", async () => {
-    const facebookPsidLogin = vi.fn(async () =>
-      FacebookPsidLoginResponseSchema.parse({
-        token: "guest-token",
-        matchedBy: "psid_incomplete",
-        fbPsid: "psid-1",
-        hasCompleteFacebookIdentity: false,
-        isGuest: true,
-        userId: "guest-1",
-      }),
-    );
-    const { repository, storage, userStorage } = createRepository({
-      facebookPsidLogin,
-    });
-
-    const result = await repository.facebookPsidLogin({
-      psid: "psid-1",
-      deviceId: "device-1",
-    });
-
-    expect(result).toEqual(Result.ok(LoginStatus.Guest));
-    expect(storage.setGuestToken).toHaveBeenCalledWith("guest-token");
-    expect(storage.setLoginProvider).toHaveBeenCalledWith(LoginStatus.Guest);
-    expect(storage.setDeviceId).toHaveBeenCalledWith("device-1");
-    expect(userStorage.setUserId).toHaveBeenCalledWith("guest-1");
-  });
-
-  it("does not report guest psid login success when session persistence fails", async () => {
-    const storageError = new Error("guest token write failed");
-    const facebookPsidLogin = vi.fn(async () =>
-      FacebookPsidLoginResponseSchema.parse({
-        token: "guest-token",
-        matchedBy: "psid_incomplete",
-        fbPsid: "psid-1",
-        hasCompleteFacebookIdentity: false,
-        isGuest: true,
-        userId: "guest-1",
-      }),
-    );
-    const { repository, storage } = createRepository({ facebookPsidLogin });
-    vi.mocked(storage.setGuestToken).mockResolvedValueOnce(
-      Result.err(storageError),
-    );
-
-    const result = await repository.facebookPsidLogin({ psid: "psid-1" });
-
-    expect(Result.isErr(result)).toBe(true);
-    expect(storage.setLoginProvider).not.toHaveBeenCalled();
-  });
 });

src/data/repositories/__tests__/auth_repository.session.test.ts

@@ -239,4 +239,27 @@ describe("AuthRepository session Result handling", () => {
 
     expect(result).toEqual(Result.ok(loginResponse.user));
   });
+
+  it("persists a top-up handoff as a formal Messenger session", async () => {
+    const handoffResponse = {
+      ...loginResponse,
+      loginStatus: LoginStatus.FacebookMessenger,
+      merged: false,
+    } as const;
+    const { repository, storage, userStorage } = createRepository({
+      api: {
+        consumeTopUpHandoff: vi.fn(async () => handoffResponse),
+      },
+    });
+
+    const result = await repository.consumeTopUpHandoff("x".repeat(32));
+
+    expect(result).toEqual(Result.ok(LoginStatus.FacebookMessenger));
+    expect(storage.setLoginToken).toHaveBeenCalledWith("login-token");
+    expect(storage.setRefreshToken).toHaveBeenCalledWith("refresh-token");
+    expect(userStorage.setUserId).toHaveBeenCalledWith("user-1");
+    expect(storage.setLoginProvider).toHaveBeenCalledWith(
+      LoginStatus.FacebookMessenger,
+    );
+  });
 });

src/data/repositories/auth_repository.ts

@@ -3,18 +3,17 @@ import type { IAuthRepository } from "@/data/repositories/interfaces";
 import {
   FacebookIdentityRequestSchema,
   FacebookLoginRequestSchema,
-  FacebookPsidLoginRequestSchema,
   FbIdLoginRequestSchema,
   GoogleLoginRequestSchema,
   GuestLoginRequestSchema,
   GuestLoginResponse,
   LoginRequestSchema,
   LoginResponse,
-  LoginResponseSchema,
   LoginStatus,
   RefreshTokenRequestSchema,
   RefreshTokenResponse,
   RegisterRequestSchema,
+  TopUpHandoffRequestSchema,
   type LoginStatus as LoginStatusT,
 } from "@/data/schemas/auth";
 import { User } from "@/data/schemas/user";
@@ -264,54 +263,16 @@ export class AuthRepository implements IAuthRepository {
     });
   }
 
-  /** 通过 Facebook PSID 直接登录或返回游客态。 */
+  /** 消费一次性充值凭证并按后端返回的 canonical 账号建立正式会话。 */
-  async facebookPsidLogin(input: {
+  async consumeTopUpHandoff(
-    psid: string;
+    handoffToken: string,
-    deviceId?: string;
+  ): Promise<Result<LoginStatusT>> {
-    bindToGuest?: boolean;
-  }): Promise<Result<LoginStatusT>> {
     return Result.wrap(async () => {
-      const response = await this.api.facebookPsidLogin(
+      const response = await this.api.consumeTopUpHandoff(
-        FacebookPsidLoginRequestSchema.parse({
+        TopUpHandoffRequestSchema.parse({ handoffToken }),
-          psid: input.psid,
-          deviceId: input.deviceId ?? "",
-          bindToGuest: input.bindToGuest ?? true,
-        }),
       );
-      const data = response;
+      await this._saveLoginData(response, response.loginStatus);
-      await this._saveFacebookIdentity({
+      return response.loginStatus;
-        asid: data.fbAsid,
-        psid: data.fbPsid,
-      });
-
-      if (data.isGuest || !data.hasCompleteFacebookIdentity) {
-        const tokenResult = await this.storage.setGuestToken(data.token);
-        if (Result.isErr(tokenResult)) throw tokenResult.error;
-        if (input.deviceId) {
-          const deviceResult = await this.storage.setDeviceId(input.deviceId);
-          if (Result.isErr(deviceResult)) throw deviceResult.error;
-        }
-        const userId = data.userId || data.user?.id || "";
-        if (userId) {
-          const userIdResult = await this.userStorage.setUserId(userId);
-          if (Result.isErr(userIdResult)) throw userIdResult.error;
-        }
-        const providerResult = await this.storage.setLoginProvider(
-          LoginStatus.Guest,
-        );
-        if (Result.isErr(providerResult)) throw providerResult.error;
-        return LoginStatus.Guest;
-      }
-
-      await this._saveLoginData(
-        LoginResponseSchema.parse({
-          token: data.token,
-          refreshToken: data.refreshToken,
-          user: data.user ?? { id: data.userId },
-        }),
-        LoginStatus.Facebook,
-      );
-      return LoginStatus.Facebook;
     });
   }
 

src/data/repositories/interfaces/iauth_repository.ts

@@ -71,12 +71,8 @@ export interface IAuthRepository {
     psid?: string;
   }): Promise<Result<void>>;
 
-  /** 通过 Facebook PSID 直接登录或返回游客态。 */
+  /** 消费一次性充值登录凭证并建立正式会话。 */
-  facebookPsidLogin(input: {
+  consumeTopUpHandoff(handoffToken: string): Promise<Result<LoginStatus>>;
-    psid: string;
-    deviceId?: string;
-    bindToGuest?: boolean;
-  }): Promise<Result<LoginStatus>>;
 
   /** 刷新 token：先读本地的 refresh token，空则返回错误。 */
   refreshToken(): Promise<Result<RefreshTokenResponse>>;

src/data/repositories/interfaces/ipayment_repository.ts

@@ -13,7 +13,10 @@ import type { Result } from "@/utils/result";
 
 export interface IPaymentRepository {
   /** 获取套餐列表。 */
-  getPlans(commercialOfferId?: string): Promise<Result<PaymentPlansResponse>>;
+  getPlans(
+    commercialOfferId?: string,
+    supportCharacterId?: string,
+  ): Promise<Result<PaymentPlansResponse>>;
 
   /** 获取本地缓存套餐列表。 */
   getCachedPlans(): Promise<Result<PaymentPlansResponse | null>>;

src/data/repositories/payment_repository.ts

@@ -24,10 +24,18 @@ export class PaymentRepository implements IPaymentRepository {
   constructor(private readonly api: PaymentApi) {}
 
   /** 获取套餐列表。 */
-  async getPlans(commercialOfferId?: string): Promise<Result<PaymentPlansResponse>> {
+  async getPlans(
+    commercialOfferId?: string,
+    supportCharacterId?: string,
+  ): Promise<Result<PaymentPlansResponse>> {
     return Result.wrap(async () => {
-      const response = await this.api.getPlans(commercialOfferId);
+      const response = await this.api.getPlans(
-      if (!commercialOfferId) await PaymentPlansStorage.setPlans(response);
+        commercialOfferId,
+        supportCharacterId,
+      );
+      if (!commercialOfferId && !supportCharacterId) {
+        await PaymentPlansStorage.setPlans(response);
+      }
       return response;
     });
   }

src/data/schemas/auth/__tests__/facebook_identity.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, it } from "vitest";
 
 import {
   FacebookIdentityResponseSchema,
-  FacebookPsidLoginResponseSchema,
   LoginRequestSchema,
+  TopUpHandoffResponseSchema,
 } from "@/data/schemas/auth";
 import { UserSchema } from "@/data/schemas/user/user";
 
@@ -28,41 +28,6 @@ describe("facebook identity schema models", () => {
     });
   });
 
-  it("parses facebook psid login responses for real users and guests", () => {
-    expect(
-      FacebookPsidLoginResponseSchema.parse({
-        token: "login-token",
-        refreshToken: "refresh-token",
-        matchedBy: "psid",
-        fbAsid: "asid-1",
-        fbPsid: "psid-1",
-        hasCompleteFacebookIdentity: true,
-        isGuest: false,
-        user: { id: "user-1", username: "Elio" },
-      }),
-    ).toMatchObject({
-      isGuest: false,
-      hasCompleteFacebookIdentity: true,
-      user: { id: "user-1" },
-    });
-
-    expect(
-      FacebookPsidLoginResponseSchema.parse({
-        token: "guest-token",
-        matchedBy: "guest",
-        fbPsid: "psid-1",
-        hasCompleteFacebookIdentity: false,
-        isGuest: true,
-        userId: "guest-1",
-      }),
-    ).toMatchObject({
-      refreshToken: "",
-      isGuest: true,
-      userId: "guest-1",
-      user: null,
-    });
-  });
-
   it("keeps psid in request serialization without a public field declaration", () => {
     const request = LoginRequestSchema.parse({
       email: "user@example.com",
@@ -75,6 +40,21 @@ describe("facebook identity schema models", () => {
     expect(request).toMatchObject({ psid: "psid-1" });
   });
 
+  it("parses a formal Messenger top-up handoff session", () => {
+    expect(
+      TopUpHandoffResponseSchema.parse({
+        token: "login-token",
+        refreshToken: "refresh-token",
+        loginStatus: "facebookMessenger",
+        merged: false,
+        user: { id: "user-1", username: "Messenger User" },
+      }),
+    ).toMatchObject({
+      loginStatus: "facebookMessenger",
+      user: { id: "user-1" },
+    });
+  });
+
   it("accepts facebook identity fields in user schema", () => {
     expect(
       UserSchema.parse({

src/data/schemas/auth/index.ts

@@ -6,16 +6,16 @@ export * from "./facebook_user_data";
 export * from "./login_status";
 export * from "./request/facebook_identity_request";
 export * from "./request/facebook_login_request";
-export * from "./request/facebook_psid_login_request";
 export * from "./request/fb_id_login_request";
 export * from "./request/google_login_request";
 export * from "./request/guest_login_request";
 export * from "./request/login_request";
 export * from "./request/refresh_token_request";
 export * from "./request/register_request";
+export * from "./request/top_up_handoff_request";
 export * from "./response/facebook_identity_response";
-export * from "./response/facebook_psid_login_response";
 export * from "./response/guest_login_response";
 export * from "./response/login_response";
 export * from "./response/logout_response";
 export * from "./response/refresh_token_response";
+export * from "./response/top_up_handoff_response";

src/data/schemas/auth/login_status.ts

@@ -3,6 +3,7 @@ export const LoginStatus = {
   NotLoggedIn: "notLoggedIn",
   Guest: "guest",
   Facebook: "facebook",
+  FacebookMessenger: "facebookMessenger",
   Google: "google",
   Email: "email",
 } as const;

src/data/schemas/auth/request/facebook_psid_login_request.ts

@@ -1,22 +0,0 @@
-/**
- * Facebook PSID 登录请求
- */
-import { z } from "zod";
-
-import { booleanOrTrue, stringOrEmpty } from "../../nullable-defaults";
-
-export const FacebookPsidLoginRequestSchema = z
-  .object({
-    psid: z.string(),
-    deviceId: stringOrEmpty,
-    bindToGuest: booleanOrTrue,
-  })
-  .readonly();
-
-export type FacebookPsidLoginRequestInput = z.input<
-  typeof FacebookPsidLoginRequestSchema
->;
-export type FacebookPsidLoginRequestData = z.output<
-  typeof FacebookPsidLoginRequestSchema
->;
-export type FacebookPsidLoginRequest = FacebookPsidLoginRequestData;

src/data/schemas/auth/request/index.ts

@@ -4,10 +4,10 @@
 
 export * from "./facebook_identity_request";
 export * from "./facebook_login_request";
-export * from "./facebook_psid_login_request";
 export * from "./fb_id_login_request";
 export * from "./google_login_request";
 export * from "./guest_login_request";
 export * from "./login_request";
 export * from "./refresh_token_request";
 export * from "./register_request";
+export * from "./top_up_handoff_request";

src/data/schemas/auth/request/top_up_handoff_request.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const TopUpHandoffRequestSchema = z
+  .object({
+    handoffToken: z.string().min(32).max(512),
+  })
+  .readonly();
+
+export type TopUpHandoffRequest = z.output<
+  typeof TopUpHandoffRequestSchema
+>;

src/data/schemas/auth/response/facebook_psid_login_response.ts

@@ -1,34 +0,0 @@
-/**
- * Facebook PSID 登录响应
- */
-import { z } from "zod";
-
-import {
-  booleanOrFalse,
-  schemaOrNull,
-  stringOrEmpty,
-} from "../../nullable-defaults";
-import { UserSchema } from "../../user/user";
-
-export const FacebookPsidLoginResponseSchema = z
-  .object({
-    token: z.string(),
-    refreshToken: stringOrEmpty,
-    matchedBy: stringOrEmpty,
-    fbAsid: stringOrEmpty,
-    fbPsid: stringOrEmpty,
-    hasCompleteFacebookIdentity: booleanOrFalse,
-    isGuest: booleanOrFalse,
-    user: schemaOrNull(UserSchema),
-    userId: stringOrEmpty,
-  })
-  .readonly();
-
-export type FacebookPsidLoginResponseInput = z.input<
-  typeof FacebookPsidLoginResponseSchema
->;
-export type FacebookPsidLoginResponseData = z.output<
-  typeof FacebookPsidLoginResponseSchema
->;
-
-export type FacebookPsidLoginResponse = FacebookPsidLoginResponseData;

src/data/schemas/auth/response/index.ts

@@ -3,8 +3,8 @@
  */
 
 export * from "./facebook_identity_response";
-export * from "./facebook_psid_login_response";
 export * from "./guest_login_response";
 export * from "./login_response";
 export * from "./logout_response";
 export * from "./refresh_token_response";
+export * from "./top_up_handoff_response";

src/data/schemas/auth/response/top_up_handoff_response.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+import { stringOrEmpty } from "../../nullable-defaults";
+import { UserSchema } from "../../user/user";
+
+export const TopUpHandoffResponseSchema = z
+  .object({
+    user: UserSchema,
+    token: z.string(),
+    refreshToken: stringOrEmpty,
+    loginStatus: z.enum([
+      "email",
+      "google",
+      "facebook",
+      "facebookMessenger",
+    ]),
+    merged: z.boolean().default(false),
+  })
+  .readonly();
+
+export type TopUpHandoffResponse = z.output<
+  typeof TopUpHandoffResponseSchema
+>;

src/data/schemas/chat/__tests__/payment_guidance.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  ChatLockDetailSchema,
+  ChatSendResponseSchema,
+  PaymentGuidanceSchema,
+  UnlockHistoryResponseSchema,
+  UnlockPrivateResponseSchema,
+} from "@/data/schemas/chat";
+
+const guidance = {
+  guidanceId: "guidance-1",
+  characterId: "maya-tan",
+  characterName: "Maya Tan",
+  scene: "voiceLocked",
+  mode: "guide",
+  title: "Keep talking with Maya",
+  copy: "Hey love, I want to keep talking. This voice message needs 20 credits.",
+  ctaLabel: "View VIP & credit options",
+  purchaseOptions: ["vip", "topup"],
+  target: "subscription",
+  ruleId: "payment_guidance_voiceLocked",
+} as const;
+
+describe("payment guidance wire contract", () => {
+  it("parses the public decision without changing role identity", () => {
+    expect(PaymentGuidanceSchema.parse(guidance)).toEqual(guidance);
+  });
+
+  it("accepts the supportCharacter guidance scene", () => {
+    expect(
+      PaymentGuidanceSchema.parse({
+        ...guidance,
+        scene: "supportCharacter",
+        ruleId: "payment_guidance_supportCharacter",
+      }).scene,
+    ).toBe("supportCharacter");
+  });
+
+  it("keeps all backend lock facts instead of dropping hint and CTA", () => {
+    expect(
+      ChatLockDetailSchema.parse({
+        locked: true,
+        showContent: false,
+        showUpgrade: true,
+        reason: "voice_message",
+        hint: "This voice message needs 20 credits.",
+        actionLabel: "Unlock",
+        detail: { requiredCredits: 20 },
+      }),
+    ).toEqual({
+      locked: true,
+      showContent: false,
+      showUpgrade: true,
+      reason: "voice_message",
+      hint: "This voice message needs 20 credits.",
+      actionLabel: "Unlock",
+      detail: { requiredCredits: 20 },
+    });
+  });
+
+  it("keeps backward compatibility when guidance is absent", () => {
+    const parsed = ChatSendResponseSchema.parse({ reply: "Hello" });
+    expect(parsed.paymentGuidance).toBeNull();
+  });
+
+  it("parses guidance on chat and both unlock responses", () => {
+    expect(
+      ChatSendResponseSchema.parse({
+        reply: "",
+        canSendMessage: false,
+        paymentGuidance: guidance,
+      }).paymentGuidance,
+    ).toEqual(guidance);
+    expect(
+      UnlockPrivateResponseSchema.parse({
+        unlocked: false,
+        reason: "insufficient_credits",
+        paymentGuidance: guidance,
+      }).paymentGuidance,
+    ).toEqual(guidance);
+    expect(
+      UnlockHistoryResponseSchema.parse({
+        unlocked: false,
+        reason: "insufficient_balance",
+        paymentGuidance: { ...guidance, scene: "historyLocked" },
+      }).paymentGuidance?.scene,
+    ).toBe("historyLocked");
+  });
+});

src/data/schemas/chat/chat_payloads.ts

@@ -3,7 +3,11 @@
  */
 import { z } from "zod";
 
-import { booleanOrFalse, schemaOr, stringOrNull } from "../nullable-defaults";
+import {
+  booleanOrFalse,
+  schemaOr,
+  stringOrNull,
+} from "../nullable-defaults";
 
 const CHAT_IMAGE_DEFAULTS = { type: null, url: null } as const;
 
@@ -23,7 +27,12 @@ export const ChatImageSchema = schemaOr(
 export const ChatLockDetailSchema = schemaOr(
   z.object({
     locked: booleanOrFalse,
+    showContent: z.boolean().nullish(),
+    showUpgrade: z.boolean().nullish(),
     reason: stringOrNull,
+    hint: z.string().nullish(),
+    actionLabel: z.string().nullish(),
+    detail: z.record(z.string(), z.unknown()).nullish(),
   }),
   CHAT_LOCK_DETAIL_DEFAULTS,
 ).readonly();

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

@@ -13,6 +13,42 @@ import {
 import { ChatImageSchema, ChatLockDetailSchema } from "../chat_payloads";
 import { ChatActionSchema } from "../chat_action";
 
+export const PaymentGuidanceSceneSchema = z.enum([
+  "vip",
+  "insufficientCredits",
+  "chatInterrupted",
+  "voiceLocked",
+  "imageLocked",
+  "privateMessageLocked",
+  "historyLocked",
+  "privateZoneLocked",
+  "unknownLock",
+  "whyPay",
+  "supportCharacter",
+  "leavingAfterCredits",
+  "paymentIssue",
+  "externalRisk",
+  "purchaseOptions",
+]);
+
+export const PaymentGuidanceSchema = z
+  .object({
+    guidanceId: z.string().min(1),
+    characterId: z.string().min(1),
+    characterName: z.string().min(1),
+    scene: PaymentGuidanceSceneSchema,
+    mode: z.enum(["guide", "careOnly", "issueSupport", "riskReminder"]),
+    title: z.string().nullable().default(null),
+    copy: z.string().min(1),
+    ctaLabel: z.string().nullable().default(null),
+    purchaseOptions: z.array(z.enum(["vip", "topup"])).readonly(),
+    target: z.enum(["subscription", "giftCatalog"]).nullable().default(null),
+    ruleId: z.string().min(1),
+  })
+  .readonly();
+
+export type PaymentGuidance = z.output<typeof PaymentGuidanceSchema>;
+
 export const CommercialActionSchema = z
   .object({
     actionId: z.string().min(1),
@@ -42,6 +78,7 @@ export const ChatSendResponseSchema = z
     requiredCredits: numberOrZero,
     shortfallCredits: numberOrZero,
     commercialAction: CommercialActionSchema.nullish().default(null),
+    paymentGuidance: PaymentGuidanceSchema.nullish().default(null),
     chatAction: ChatActionSchema.nullish().default(null),
   })
   .readonly();

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

@@ -9,6 +9,7 @@ import {
   numberOrZero,
   recordOrEmpty,
 } from "../../nullable-defaults";
+import { PaymentGuidanceSchema } from "./chat_send_response";
 
 export const UnlockHistoryCostsByMessageSchema = recordOrEmpty(z.number());
 
@@ -33,6 +34,7 @@ export const UnlockHistoryResponseSchema = z
     shortfallCredits: numberOrZero,
     costsByMessage: UnlockHistoryCostsByMessageSchema,
     messageIds: arrayOrEmpty(z.string()),
+    paymentGuidance: PaymentGuidanceSchema.nullish().default(null),
   })
   .readonly();
 

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

@@ -8,6 +8,7 @@ import {
 } from "../../nullable-defaults";
 import { ChatLockTypeSchema } from "../chat_lock_type";
 import { ChatImageSchema } from "../chat_payloads";
+import { PaymentGuidanceSchema } from "./chat_send_response";
 
 /**
  * 单条历史付费 / 私密消息解锁响应。
@@ -28,6 +29,7 @@ export const UnlockPrivateResponseSchema = z
     creditsCharged: numberOrZero,
     requiredCredits: numberOrZero,
     shortfallCredits: numberOrZero,
+    paymentGuidance: PaymentGuidanceSchema.nullish().default(null),
   })
   .readonly();
 

src/data/schemas/payment/__tests__/payment_plan.test.ts

@@ -195,9 +195,11 @@ describe("PaymentPlansResponse", () => {
 
   it("parses one user-bound commercial offer and its discounted plan", () => {
     const response = PaymentPlansResponseSchema.parse({
+        supportCharacterId: "maya-tan",
         commercialOffer: {
           enabled: true,
           commercialOfferId: "offer-1",
+          characterId: "maya-tan",
         planId: "vip_annual",
         discountPercent: 30,
         pricePercent: 70,
@@ -225,6 +227,8 @@ describe("PaymentPlansResponse", () => {
     });
 
     expect(response.commercialOffer?.commercialOfferId).toBe("offer-1");
+    expect(response.supportCharacterId).toBe("maya-tan");
+    expect(response.commercialOffer?.characterId).toBe("maya-tan");
     expect(response.plans[0]).toMatchObject({
       planId: "vip_annual",
       commercialOfferId: "offer-1",

src/data/schemas/payment/response/payment_plans_response.ts

@@ -24,6 +24,7 @@ export const CommercialOfferSummarySchema = z
   .object({
     enabled: booleanOrFalse,
     commercialOfferId: z.string().min(1),
+    characterId: stringOrEmpty,
     planId: z.string().min(1),
     discountPercent: numberOrZero,
     pricePercent: numberOrZero,
@@ -36,6 +37,7 @@ export const CommercialOfferSummarySchema = z
 export const PaymentPlansResponseSchema = z
   .object({
     isFirstRecharge: booleanOrFalse,
+    supportCharacterId: stringOrEmpty,
     firstRechargeOffer: schemaOrNull(FirstRechargeOfferSchema),
     commercialOffer: schemaOrNull(CommercialOfferSummarySchema),
     plans: arrayOrEmpty(PaymentPlanSchema),