feat(chat): prompt before credit top up

src/app/chat/chat-screen.tsx

@@ -30,6 +30,7 @@ import {
   ChatQuotaExhaustedBanner,
   ExternalBrowserDialog,
   HistoryUnlockDialog,
+  InsufficientCreditsDialog,
   PwaInstallOverlay,
 } from "./components";
 import {
@@ -49,6 +50,7 @@ export function ChatScreen() {
   const router = useRouter();
   const [showExternalBrowserDialog, setShowExternalBrowserDialog] =
     useState(false);
+  const unlockPaywallRequest = state.unlockPaywallRequest;
 
   // isGuest 派生（chat-screen 是唯一知道这个值的地方 —— chat 机器无 isGuest 字段）
   const isGuest = deriveIsGuest(authState.loginStatus);
@@ -132,13 +134,16 @@ export function ChatScreen() {
     state.historyLoaded,
   ]);
 
-  useEffect(() => {
+  function handleCloseInsufficientCreditsDialog(): void {
-    const request = state.unlockPaywallRequest;
+    chatDispatch({ type: "ChatUnlockPaywallNavigationConsumed" });
-    if (!request) return;
+  }
+
+  function handleConfirmInsufficientCreditsDialog(): void {
+    if (!unlockPaywallRequest) return;
 
     savePendingChatUnlock({
-      messageId: request.messageId,
+      messageId: unlockPaywallRequest.messageId,
-      kind: request.kind,
+      kind: unlockPaywallRequest.kind,
       returnUrl: ROUTES.chat,
       stage: "payment",
     });
@@ -149,12 +154,7 @@ export function ChatScreen() {
         { returnTo: "chat" },
       ),
     );
-  }, [
+  }
-    chatDispatch,
-    router,
-    state.unlockPaywallRequest,
-    userState.isVip,
-  ]);
 
   async function handleOpenExternalBrowser(): Promise<void> {
     setShowExternalBrowserDialog(false);
@@ -263,6 +263,15 @@ export function ChatScreen() {
           onClose={() => chatDispatch({ type: "ChatUnlockHistoryDismissed" })}
           onConfirm={() => chatDispatch({ type: "ChatUnlockHistoryConfirmed" })}
         />
+
+        <InsufficientCreditsDialog
+          open={unlockPaywallRequest !== null}
+          creditBalance={unlockPaywallRequest?.creditBalance ?? 0}
+          requiredCredits={unlockPaywallRequest?.requiredCredits ?? 0}
+          shortfallCredits={unlockPaywallRequest?.shortfallCredits ?? 0}
+          onClose={handleCloseInsufficientCreditsDialog}
+          onConfirm={handleConfirmInsufficientCreditsDialog}
+        />
       </div>
     </MobileShell>
   );

src/app/chat/components/index.ts

@@ -16,6 +16,7 @@ export * from "./external-browser-dialog";
 export * from "./fullscreen-image-viewer";
 export * from "./history-unlock-dialog";
 export * from "./image-bubble";
+export * from "./insufficient-credits-dialog";
 export * from "./language-dialog";
 export * from "./lottie-message-bubble";
 export * from "./message-avatar";

src/app/chat/components/insufficient-credits-dialog.module.css

@@ -0,0 +1,102 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 220;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  background: rgba(0, 0, 0, 0.52);
+}
+
+.dialog {
+  width: 100%;
+  max-width: var(--pwa-install-dialog-max-width, 360px);
+  padding: 24px 18px 18px;
+  text-align: center;
+  background: var(--color-page-background, #ffffff);
+  border: 1px solid rgba(246, 87, 160, 0.16);
+  border-radius: 36px;
+  box-shadow: 0 18px 46px rgba(38, 18, 31, 0.18);
+}
+
+.title {
+  margin: 0 0 10px;
+  color: var(--color-text-foreground, #171717);
+  font-size: var(--font-size-22, 22px);
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+.content {
+  margin: 0 12px 18px;
+  color: #393939;
+  font-size: var(--font-size-lg, 16px);
+  line-height: 1.5;
+}
+
+.creditList {
+  display: grid;
+  gap: 8px;
+  margin: 0 0 18px;
+  padding: 12px;
+  background: #fff4f9;
+  border-radius: 22px;
+}
+
+.creditItem {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  color: #4a3b43;
+  font-size: var(--font-size-md, 14px);
+  line-height: 1.3;
+}
+
+.creditItem dt {
+  margin: 0;
+  font-weight: 500;
+}
+
+.creditItem dd {
+  margin: 0;
+  color: #f657a0;
+  font-size: var(--font-size-lg, 16px);
+  font-weight: 800;
+}
+
+.actions {
+  display: flex;
+  gap: var(--spacing-md, 12px);
+  width: 100%;
+}
+
+.button {
+  flex: 1 1 auto;
+  height: var(--pwa-button-height, 44px);
+  border: 0;
+  border-radius: var(--radius-bottom-sheet, 28px);
+  font-size: var(--font-size-lg, 16px);
+  font-weight: 700;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.secondary {
+  color: var(--color-page-background, #ffffff);
+  background: var(--color-text-secondary, #9e9e9e);
+}
+
+.primary {
+  color: var(--color-page-background, #ffffff);
+  background: linear-gradient(90deg, #ff67e0 0%, #ff52a2 100%);
+  box-shadow: 0 6px 14px rgba(246, 87, 160, 0.28);
+}
+
+.button:focus-visible {
+  outline: 2px solid #f657a0;
+  outline-offset: 3px;
+}

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

@@ -0,0 +1,77 @@
+"use client";
+
+import styles from "./insufficient-credits-dialog.module.css";
+
+export interface InsufficientCreditsDialogProps {
+  open: boolean;
+  creditBalance: number;
+  requiredCredits: number;
+  shortfallCredits: number;
+  onClose: () => void;
+  onConfirm: () => void;
+}
+
+export function InsufficientCreditsDialog({
+  open,
+  creditBalance,
+  requiredCredits,
+  shortfallCredits,
+  onClose,
+  onConfirm,
+}: InsufficientCreditsDialogProps) {
+  if (!open) return null;
+
+  const showCreditDetail = requiredCredits > 0 || shortfallCredits > 0;
+
+  return (
+    <div
+      className={styles.overlay}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="insufficient-credits-title"
+    >
+      <div className={styles.dialog}>
+        <h2 id="insufficient-credits-title" className={styles.title}>
+          Not enough credits
+        </h2>
+        <p className={styles.content}>
+          Top up your credits to unlock this message and keep the moment going.
+        </p>
+
+        {showCreditDetail ? (
+          <dl className={styles.creditList}>
+            <div className={styles.creditItem}>
+              <dt>Balance</dt>
+              <dd>{creditBalance}</dd>
+            </div>
+            <div className={styles.creditItem}>
+              <dt>Required</dt>
+              <dd>{requiredCredits}</dd>
+            </div>
+            <div className={styles.creditItem}>
+              <dt>Still needed</dt>
+              <dd>{shortfallCredits}</dd>
+            </div>
+          </dl>
+        ) : null}
+
+        <div className={styles.actions}>
+          <button
+            type="button"
+            className={`${styles.button} ${styles.secondary}`}
+            onClick={onClose}
+          >
+            Later
+          </button>
+          <button
+            type="button"
+            className={`${styles.button} ${styles.primary}`}
+            onClick={onConfirm}
+          >
+            Top up now
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

src/app/chat/image/[messageId]/chat-image-viewer-screen.tsx

@@ -15,7 +15,11 @@ import {
 } from "@/lib/navigation/chat_unlock_session";
 
 import { getInsufficientCreditsSubscriptionType } from "../../chat-screen.helpers";
-import { FullscreenImageViewer, HistoryUnlockDialog } from "../../components";
+import {
+  FullscreenImageViewer,
+  HistoryUnlockDialog,
+  InsufficientCreditsDialog,
+} from "../../components";
 import styles from "./chat-image-viewer-screen.module.css";
 
 export interface ChatImageViewerScreenProps {
@@ -31,6 +35,11 @@ export function ChatImageViewerScreen({
   const chatState = useChatState();
   const chatDispatch = useChatDispatch();
   const returnUrl = ROUTE_BUILDERS.chatImage(messageId);
+  const unlockPaywallRequest =
+    chatState.unlockPaywallRequest?.kind === "image" &&
+    chatState.unlockPaywallRequest.messageId === messageId
+      ? chatState.unlockPaywallRequest
+      : null;
   const isAuthenticatedUser =
     authState.loginStatus !== "notLoggedIn" &&
     authState.loginStatus !== "guest";
@@ -67,15 +76,16 @@ export function ChatImageViewerScreen({
     returnUrl,
   ]);
 
-  useEffect(() => {
+  const handleCloseInsufficientCreditsDialog = () => {
-    const request = chatState.unlockPaywallRequest;
+    chatDispatch({ type: "ChatUnlockPaywallNavigationConsumed" });
-    if (!request || request.kind !== "image" || request.messageId !== messageId) {
+  };
-      return;
+
-    }
+  const handleConfirmInsufficientCreditsDialog = () => {
+    if (!unlockPaywallRequest) return;
 
     savePendingChatUnlock({
-      messageId: request.messageId,
+      messageId: unlockPaywallRequest.messageId,
-      kind: request.kind,
+      kind: unlockPaywallRequest.kind,
       returnUrl,
       stage: "payment",
     });
@@ -86,14 +96,7 @@ export function ChatImageViewerScreen({
         { returnTo: "chat" },
       ),
     );
-  }, [
+  };
-    chatDispatch,
-    chatState.unlockPaywallRequest,
-    messageId,
-    returnUrl,
-    router,
-    userState.isVip,
-  ]);
 
   const handleClose = () => {
     router.push(ROUTES.chat);
@@ -119,14 +122,24 @@ export function ChatImageViewerScreen({
   };
 
   const historyUnlockDialog = (
-    <HistoryUnlockDialog
+    <>
-      open={chatState.unlockHistoryPromptVisible}
+      <HistoryUnlockDialog
-      lockedCount={chatState.lockedHistoryCount}
+        open={chatState.unlockHistoryPromptVisible}
-      isLoading={chatState.isUnlockingHistory}
+        lockedCount={chatState.lockedHistoryCount}
-      errorMessage={chatState.unlockHistoryError}
+        isLoading={chatState.isUnlockingHistory}
-      onClose={() => chatDispatch({ type: "ChatUnlockHistoryDismissed" })}
+        errorMessage={chatState.unlockHistoryError}
-      onConfirm={() => chatDispatch({ type: "ChatUnlockHistoryConfirmed" })}
+        onClose={() => chatDispatch({ type: "ChatUnlockHistoryDismissed" })}
-    />
+        onConfirm={() => chatDispatch({ type: "ChatUnlockHistoryConfirmed" })}
+      />
+      <InsufficientCreditsDialog
+        open={unlockPaywallRequest !== null}
+        creditBalance={unlockPaywallRequest?.creditBalance ?? 0}
+        requiredCredits={unlockPaywallRequest?.requiredCredits ?? 0}
+        shortfallCredits={unlockPaywallRequest?.shortfallCredits ?? 0}
+        onClose={handleCloseInsufficientCreditsDialog}
+        onConfirm={handleConfirmInsufficientCreditsDialog}
+      />
+    </>
   );
 
   if (!message) {