fix:APP-push点击文案显示home页

Reviewed-on: #22

.cursor/commands/myspec.split-spec.md

@@ -1,4 +1,4 @@
-当前有一个很大的 spec.md（大需求规范），需要按业务逻辑拆分成多个子模块规范。
+当前有一个很大的 spec.md（大需求规范），需要按业务逻辑合理拆分成多个子模块规范。
 
 请按以下规则拆分：
 

.gitea/workflows/server-deploy.yml

@@ -56,6 +56,9 @@ jobs:
       # 健康检查路径（未配置则默认 /health；如果你没有 health 接口，可改为 /docs 或 /）
       HEALTHCHECK_PATH: ${{ vars.HEALTHCHECK_PATH }}
 
+      # 定时服务健康检查路径（检查 Redis/Worker/Beat；未配置则默认 /v1/push/scheduler/health）
+      SCHEDULER_HEALTHCHECK_PATH: ${{ vars.SCHEDULER_HEALTHCHECK_PATH }}
+
       # 可选：远端 env 文件路径（例如 /opt/mindfulness-server/.env.prod），存在则 docker run --env-file
       REMOTE_ENV_FILE: ${{ vars.REMOTE_ENV_FILE }}
 
@@ -258,11 +261,12 @@ jobs:
           GREEN_PORT="${GREEN_PORT:-8002}"
           CONTAINER_PORT="${CONTAINER_PORT:-8000}"
           HEALTHCHECK_PATH="${HEALTHCHECK_PATH:-/health}"
+          SCHEDULER_HEALTHCHECK_PATH="${SCHEDULER_HEALTHCHECK_PATH:-/v1/push/scheduler/health}"
 
           echo "准备部署：${DOCKER_IMAGE}:${DEPLOY_TAG} -> ${DEPLOY_ENV} (${SSH_USER}@${SSH_HOST}:${SSH_PORT})"
 
           ssh -p "${SSH_PORT}" -i ~/.ssh/id_rsa -o StrictHostKeyChecking=yes -o IdentitiesOnly=yes "${SSH_USER}@${SSH_HOST}" bash -s -- \
-            "${DOCKER_IMAGE}" "${DEPLOY_TAG}" "${NGINX_UPSTREAM_FILE}" "${NGINX_UPSTREAM_NAME}" "${BLUE_PORT}" "${GREEN_PORT}" "${CONTAINER_PORT}" "${HEALTHCHECK_PATH}" "${REMOTE_ENV_FILE:-}" <<'REMOTE'
+            "${DOCKER_IMAGE}" "${DEPLOY_TAG}" "${NGINX_UPSTREAM_FILE}" "${NGINX_UPSTREAM_NAME}" "${BLUE_PORT}" "${GREEN_PORT}" "${CONTAINER_PORT}" "${HEALTHCHECK_PATH}" "${SCHEDULER_HEALTHCHECK_PATH}" "${REMOTE_ENV_FILE:-}" <<'REMOTE'
           set -euo pipefail
 
           IMAGE="$1"
@@ -273,7 +277,8 @@ jobs:
           GREEN_PORT="$6"
           CONTAINER_PORT="$7"
           HEALTHCHECK_PATH="$8"
-          REMOTE_ENV_FILE="$9"
+          SCHEDULER_HEALTHCHECK_PATH="$9"
+          REMOTE_ENV_FILE="${10}"
 
           APP_DIR="/opt/mindfulness-server"
           ACTIVE_FILE="${APP_DIR}/active_color"
@@ -307,9 +312,18 @@ jobs:
           # 拉取镜像
           ${SUDO} docker pull "${IMAGE}:${TAG}"
 
-          # 启动新颜色容器
+          # 启动新颜色容器（API + Worker + Beat）
+          API_NAME="mindfulness-server-api-${NEW_COLOR}"
+          WORKER_NAME="mindfulness-server-worker-${NEW_COLOR}"
+          BEAT_NAME="mindfulness-server-beat-${NEW_COLOR}"
+
+          # 兼容旧命名：之前可能只有一个 mindfulness-server-blue/green
           ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" >/dev/null 2>&1 || true
 
+          ${SUDO} docker rm -f "${API_NAME}" >/dev/null 2>&1 || true
+          ${SUDO} docker rm -f "${WORKER_NAME}" >/dev/null 2>&1 || true
+          ${SUDO} docker rm -f "${BEAT_NAME}" >/dev/null 2>&1 || true
+
           ENV_FILE_ARGS=()
           if [[ -n "${REMOTE_ENV_FILE}" && -f "${REMOTE_ENV_FILE}" ]]; then
             ENV_FILE_ARGS=(--env-file "${REMOTE_ENV_FILE}")
@@ -318,11 +332,29 @@ jobs:
             echo "提示：REMOTE_ENV_FILE 已配置但文件不存在：${REMOTE_ENV_FILE}（将忽略 env-file）"
           fi
 
+          # API（对外暴露端口，仅该容器参与蓝绿切流）
           ${SUDO} docker run -d \
-            --name "mindfulness-server-${NEW_COLOR}" \
+            --name "${API_NAME}" \
             --restart=always \
             -p "${NEW_PORT}:${CONTAINER_PORT}" \
             "${ENV_FILE_ARGS[@]}" \
+            -e START_API=1 -e START_WORKER=0 -e START_BEAT=0 \
+            "${IMAGE}:${TAG}"
+
+          # Worker（处理异步/ETA 任务，不暴露端口）
+          ${SUDO} docker run -d \
+            --name "${WORKER_NAME}" \
+            --restart=always \
+            "${ENV_FILE_ARGS[@]}" \
+            -e START_API=0 -e START_WORKER=1 -e START_BEAT=0 \
+            "${IMAGE}:${TAG}"
+
+          # Beat（定时调度，不暴露端口）
+          ${SUDO} docker run -d \
+            --name "${BEAT_NAME}" \
+            --restart=always \
+            "${ENV_FILE_ARGS[@]}" \
+            -e START_API=0 -e START_WORKER=0 -e START_BEAT=1 \
             "${IMAGE}:${TAG}"
 
           # 健康检查
@@ -350,8 +382,37 @@ jobs:
 
             if [[ "$i" -eq 30 ]]; then
               echo "健康检查失败：新版本未就绪，回滚并退出"
-              ${SUDO} docker logs --tail 200 "mindfulness-server-${NEW_COLOR}" || true
-              ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+              ${SUDO} docker logs --tail 200 "${API_NAME}" || true
+              ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
+              exit 1
+            fi
+            sleep 2
+          done
+
+          # 定时服务健康检查（确保 Redis/Worker/Beat 都 OK，避免“接口正常但定时任务没跑”）
+          if [[ "${SCHEDULER_HEALTHCHECK_PATH}" != /* ]]; then
+            SCHEDULER_HEALTHCHECK_PATH="/${SCHEDULER_HEALTHCHECK_PATH}"
+          fi
+          SCHED_URL="http://127.0.0.1:${NEW_PORT}${SCHEDULER_HEALTHCHECK_PATH}"
+          echo "定时服务健康检查：${SCHED_URL}"
+
+          # Beat 心跳是按分钟刷新，这里最多等 90 秒（45*2s）
+          for i in $(seq 1 45); do
+            RES="$(curl -fsS "${SCHED_URL}" 2>/dev/null || true)"
+            if [[ -n "${RES}" ]] \
+              && echo "${RES}" | grep -q '"redis":{"ok":true' \
+              && echo "${RES}" | grep -q '"worker":{"ok":true' \
+              && echo "${RES}" | grep -q '"beat":{"ok":true' ; then
+              echo "定时服务健康检查通过：${RES}"
+              break
+            fi
+
+            if [[ "$i" -eq 45 ]]; then
+              echo "定时服务健康检查失败：${RES}"
+              echo "Worker/Beat 日志（各 120 行）："
+              ${SUDO} docker logs --tail 120 "${WORKER_NAME}" || true
+              ${SUDO} docker logs --tail 120 "${BEAT_NAME}" || true
+              ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
               exit 1
             fi
             sleep 2
@@ -360,24 +421,24 @@ jobs:
           # 切换 Nginx upstream（在同一个 conf 文件中通过 backup 做主备切换）
           if [[ ! -f "${UPSTREAM_FILE}" ]]; then
             echo "未找到 Nginx upstream 配置文件：${UPSTREAM_FILE}"
-            ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+            ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
             exit 1
           fi
 
           if ! ${SUDO} grep -qE "upstream[[:space:]]+${UPSTREAM_NAME}[[:space:]]*\\{" "${UPSTREAM_FILE}"; then
             echo "在 ${UPSTREAM_FILE} 中未找到 upstream：${UPSTREAM_NAME}"
-            ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+            ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
             exit 1
           fi
 
           if ! ${SUDO} grep -qE "server[[:space:]]+127\\.0\\.0\\.1:${BLUE_PORT}" "${UPSTREAM_FILE}"; then
             echo "在 ${UPSTREAM_FILE} 中未找到 server 127.0.0.1:${BLUE_PORT}（请先按参考配置写入 upstream）"
-            ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+            ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
             exit 1
           fi
           if ! ${SUDO} grep -qE "server[[:space:]]+127\\.0\\.0\\.1:${GREEN_PORT}" "${UPSTREAM_FILE}"; then
             echo "在 ${UPSTREAM_FILE} 中未找到 server 127.0.0.1:${GREEN_PORT}（请先按参考配置写入 upstream）"
-            ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+            ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
             exit 1
           fi
 
@@ -416,7 +477,7 @@ jobs:
             echo "Nginx 配置校验失败，回滚 upstream 配置并退出"
             ${SUDO} cp -f "${BACKUP_FILE}" "${UPSTREAM_FILE}" || true
             ${SUDO} nginx -t && ${SUDO} nginx -s reload || true
-            ${SUDO} docker rm -f "mindfulness-server-${NEW_COLOR}" || true
+            ${SUDO} docker rm -f "${API_NAME}" "${WORKER_NAME}" "${BEAT_NAME}" >/dev/null 2>&1 || true
             exit 1
           fi
 
@@ -424,6 +485,11 @@ jobs:
           echo "${NEW_COLOR}" | ${SUDO} tee "${ACTIVE_FILE}" >/dev/null
 
           # 下线旧容器（切流后再停旧的）
+          OLD_API_NAME="mindfulness-server-api-${OLD_COLOR}"
+          OLD_WORKER_NAME="mindfulness-server-worker-${OLD_COLOR}"
+          OLD_BEAT_NAME="mindfulness-server-beat-${OLD_COLOR}"
+          ${SUDO} docker rm -f "${OLD_API_NAME}" "${OLD_WORKER_NAME}" "${OLD_BEAT_NAME}" >/dev/null 2>&1 || true
+          # 兼容旧命名
           ${SUDO} docker rm -f "mindfulness-server-${OLD_COLOR}" >/dev/null 2>&1 || true
 
           echo "部署完成：${NEW_COLOR} 已上线"

client/app.config.ts

@@ -11,11 +11,14 @@ export default ({ config }: ConfigContext): ExpoConfig => {
   const projectId =
     process.env.EXPO_PUBLIC_EAS_PROJECT_ID ||
     // 兼容部分 CI/EAS 注入的变量名
-    process.env.EAS_PROJECT_ID ||
-    undefined;
+    process.env.EAS_PROJECT_ID;
 
   return {
     ...config,
+    // ExpoConfig 的类型要求 name 必填，避免 `...config` 的可选类型导致 tsc 报错
+    name: config.name ?? 'client',
+    // slug 在绝大多数场景也建议固定为非空字符串（保持与 app.json 一致）
+    slug: config.slug ?? 'client',
     extra: {
       ...(config.extra ?? {}),
       eas: {

client/app.json

@@ -1,6 +1,6 @@
 {
   "expo": {
-    "name": "Hey Mama",
+    "name": "Dear Mama",
     "slug": "client",
     "version": "1.0.0",
     "orientation": "portrait",
@@ -9,12 +9,13 @@
     "userInterfaceStyle": "automatic",
     "newArchEnabled": true,
     "splash": {
-      "image": "./assets/images/splashScreen.png",
+      "image": "./assets/images/Screen_page.png",
       "resizeMode": "contain",
       "backgroundColor": "#EAD2BA"
     },
     "ios": {
       "supportsTablet": true,
+      "requireFullScreen": true,
       "bundleIdentifier": "com.damer.mindfulness"
     },
     "android": {

client/app/(app)/home.tsx

@@ -1,5 +1,16 @@
 import { useEffect, useLayoutEffect, useMemo, useState, useCallback, useRef } from 'react';
-import { StyleSheet, View, Dimensions, Text, Pressable, PanResponder, Animated as RNAnimated, ImageBackground } from 'react-native';
+import {
+  StyleSheet,
+  View,
+  Text,
+  Pressable,
+  PanResponder,
+  AppState,
+  Animated as RNAnimated,
+  ImageBackground,
+  Platform,
+  useWindowDimensions,
+} from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { useFocusEffect } from 'expo-router';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
@@ -19,6 +30,8 @@ import {
   getUserProfile,
   setReaction,
   setThemeMode,
+  clearPendingHomePushMessage,
+  getPendingHomePushMessage,
   getRecoFeedCache,
   setRecoFeedCache,
   getUserProfileScoring,
@@ -31,6 +44,7 @@ import {
 } from '@/src/storage/appStorage';
 
 import { fetchRecoFeed } from '@/src/services/recoApi';
+import { subscribeHomePushMessage } from '@/src/services/pushNotificationRoute';
 import { toBackendLocaleFromLanguageTag } from '@/src/i18n/locale';
 
 import ProfileModal from '@/components/home/ProfileModal';
@@ -43,8 +57,9 @@ import LikeIcon from '@/assets/images/icon/like_icon.svg';
 
 import { getBootId } from '@/src/utils/bootSession';
 import { advanceSuixinState, buildInitialSuixinState, NEUTRAL_THEME_COLORS } from '@/src/features/suixinTheme';
-
-const { height: SCREEN_HEIGHT } = Dimensions.get('window');
+import { wrapText } from '@/src/features/textWrap';
+import { defaultMeasureWidthImpl } from '@/src/features/textWrap/measure';
+import { ensureDailyWidgetRecoUpToDate } from '@/src/modules/dailyWidgetReco';
 
 // 预定义风景图列表
 const NATURE_IMAGES = [
@@ -84,7 +99,9 @@ type FeedItem = { content_id: string; text: string };
 
 export default function HomeScreen() {
   const { t, i18n } = useTranslation();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
   const isEnglish = i18n.language?.startsWith('en');
+  const isTablet = Platform.OS === 'ios' && Math.min(windowWidth, windowHeight) >= 768;
   const recoLang: 'en' | 'tc' = toBackendLocaleFromLanguageTag(i18n.language);
   const insets = useSafeAreaInsets();
   const [index, setIndex] = useState(0);
@@ -96,7 +113,41 @@ export default function HomeScreen() {
   const [busy, setBusy] = useState(false);
   const [likeFilled, setLikeFilled] = useState(false);
   const [feedItems, setFeedItems] = useState<FeedItem[]>([]);
+  const [pendingPushItem, setPendingPushItem] = useState<FeedItem | null>(null);
   const [isFetching, setIsFetching] = useState(false);
+  const [cardWidth, setCardWidth] = useState<number | null>(null);
+  const [wrappedText, setWrappedText] = useState<string>('');
+  const wrapLogRef = useRef<{ key: string } | null>(null);
+  const busyRef = useRef(false);
+  const indexRef = useRef(0);
+  const currentFeedRef = useRef<FeedItem[]>([]);
+  const likedIdsRef = useRef<Set<string>>(new Set());
+  const likeInFlightRef = useRef(false);
+
+  const applyPendingPushItem = useCallback(async (message: { notification_id: string; content_id?: number; text: string }) => {
+    const nextItem: FeedItem = {
+      content_id: message.content_id != null ? String(message.content_id) : `push:${message.notification_id}`,
+      text: message.text,
+    };
+    setPendingPushItem(nextItem);
+    indexRef.current = 0;
+    setIndex(0);
+    setLikeFilled(likedIdsRef.current.has(String(nextItem.content_id)));
+    await clearPendingHomePushMessage();
+  }, []);
+
+  const consumePendingPushItem = useCallback(async () => {
+    const pendingMessage = await getPendingHomePushMessage();
+    if (!pendingMessage?.text) return;
+    await applyPendingPushItem(pendingMessage);
+  }, [applyPendingPushItem]);
+
+  useEffect(() => {
+    busyRef.current = busy;
+  }, [busy]);
+  useEffect(() => {
+    indexRef.current = index;
+  }, [index]);
 
   // 解决语言切换时重复触发拉取/清空导致“文案不停跳动”的问题：
   // 用 ref 持有最新状态，避免 useCallback 依赖 feedItems/isFetching 造成函数 identity 变化 → effect 重复执行
@@ -159,14 +210,28 @@ export default function HomeScreen() {
 
   // 统一文案对象结构
   const currentFeed = useMemo(() => {
-    if (feedItems.length > 0) {
-      return feedItems;
+    const baseFeed =
+      feedItems.length > 0
+        ? feedItems
+        : MOCK_CONTENT.map(item => ({
+            content_id: item.id,
+            text: t(item.textKey)
+          }));
+
+    if (!pendingPushItem) {
+      return baseFeed;
     }
-    return MOCK_CONTENT.map(item => ({
-      content_id: item.id,
-      text: t(item.textKey)
-    }));
-  }, [feedItems, t]);
+
+    return [
+      pendingPushItem,
+      ...baseFeed.filter((entry) => (
+        String(entry.content_id) !== String(pendingPushItem.content_id) && entry.text !== pendingPushItem.text
+      )),
+    ];
+  }, [feedItems, pendingPushItem, t]);
+  useEffect(() => {
+    currentFeedRef.current = currentFeed;
+  }, [currentFeed]);
 
   const item = useMemo(() => {
     const data = currentFeed[index % currentFeed.length];
@@ -176,6 +241,133 @@ export default function HomeScreen() {
     };
   }, [currentFeed, index]);
 
+  // Home 文案：使用自主换行算法（Text Wrap 模块）
+  // - 通过 onLayout 获取容器宽度
+  // - 注入真实测量实现，确保“宽度派”评分与实际渲染一致
+  useEffect(() => {
+    let cancelled = false;
+
+    // 未拿到宽度前先用原文（避免闪烁）
+    if (!cardWidth || cardWidth <= 0) {
+      if (__DEV__) {
+        const key = `noWidth|${item.id}|${String(cardWidth)}`;
+        if (wrapLogRef.current?.key !== key) {
+          wrapLogRef.current = { key };
+          console.log('[TextWrap][Home] cardWidth 未就绪，先回退原文', {
+            itemId: item.id,
+            lang: recoLang,
+            cardWidth,
+            themeMode,
+          });
+        }
+      }
+      setWrappedText(item.text);
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    const paddingHorizontal = themeMode === 'scenery' ? 50 : 30;
+    const availableWidth = Math.max(0, Math.floor(cardWidth - paddingHorizontal * 2));
+
+    const lang = recoLang === 'en' ? 'EN' : 'TC';
+
+    const fontFamily =
+      lang === 'EN'
+        ? 'STIXTwoText'
+        : Platform.select({
+            ios: 'System',
+            android: 'sans-serif',
+            default: 'System',
+          });
+
+    const fontSpec = {
+      fontSize: 24,
+      fontWeight: lang === 'EN' ? '700' : '800',
+      fontFamily: String(fontFamily ?? 'System'),
+    };
+
+    (async () => {
+      try {
+        if (__DEV__) {
+          const key = `start|${item.id}|${lang}|${availableWidth}|${themeMode}`;
+          if (wrapLogRef.current?.key !== key) {
+            wrapLogRef.current = { key };
+            console.log('[TextWrap][Home] wrapText 开始', {
+              itemId: item.id,
+              lang,
+              themeMode,
+              cardWidth,
+              paddingHorizontal,
+              availableWidth,
+              fontSpec,
+              textPreview: String(item.text ?? '').slice(0, 80),
+              textLength: String(item.text ?? '').length,
+            });
+          }
+        }
+
+        const res = await wrapText({
+          text: item.text,
+          lang,
+          context: 'APP',
+          availableWidth,
+          maxLines: 3,
+          overflowMode: 'CLIP',
+          lineMode: 'AUTO',
+          // Home：采用“更偏好语气停顿/更好看”的排版风格微调（不影响算法默认 v1）
+          configVersion: 'v1-home',
+          debug: __DEV__,
+          fontSpec,
+          contextProfile: `APP|${Platform.OS}|home|${lang}`,
+          measureWidthImpl: defaultMeasureWidthImpl,
+          scoringOverrides:
+            lang === 'TC'
+              ? {
+                  // 更偏好在逗号/句号等处断行（即便宽度允许也不一定要塞满）
+                  weights: { R_PUNCT_BREAK: 180 },
+                  // 让“理想行宽”更短，避免宽屏下过度延后断行
+                  idealWidthRatio: { APP: 0.82 },
+                  // 更宽容短行（尤其是第一行在标点处停顿）
+                  minPreferredRatio: 0.45,
+                  shortLastLineRatio: 0.45,
+                }
+              : undefined,
+        });
+
+        if (cancelled) return;
+        if (__DEV__) {
+          console.log('[TextWrap][Home] wrapText 成功', {
+            itemId: item.id,
+            wrappedText: res.wrappedText,
+            linesCount: res.lines.length,
+            meta: res.meta,
+          });
+        }
+        setWrappedText(res.wrappedText);
+      } catch (error) {
+        // 任何异常都回退到原文，避免影响 Home 主流程
+        if (__DEV__) {
+          console.log('[TextWrap][Home] wrapText 异常，回退原文', {
+            itemId: item.id,
+            lang,
+            availableWidth,
+            fontSpec,
+            errorName: (error as any)?.name,
+            errorMessage: String((error as any)?.message ?? error),
+            errorStack: (error as any)?.stack,
+          });
+        }
+        if (cancelled) return;
+        setWrappedText(item.text);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [item.text, cardWidth, recoLang, themeMode]);
+
   // 异步拉取新文案
   const fetchNewFeed = useCallback(async () => {
     if (isFetchingRef.current) return;
@@ -223,13 +415,20 @@ export default function HomeScreen() {
     useCallback(() => {
       let cancelled = false;
       (async () => {
-        const mode = await getThemeMode();
-        const profile = await getUserProfile();
-        const cache = await getRecoFeedCache();
+        const [mode, profile, cache, pendingMessage] = await Promise.all([
+          getThemeMode(),
+          getUserProfile(),
+          getRecoFeedCache(),
+          getPendingHomePushMessage(),
+        ]);
 
         if (cancelled) return;
         setThemeModeState(mode);
         setProfileName(profile.name);
+        if (pendingMessage?.text) {
+          await applyPendingPushItem(pendingMessage);
+          if (cancelled) return;
+        }
 
         // 随心：若当前主题为随心，进入 Home 时确保状态就绪（仅冷启动会话重算）
         if (mode === 'suixin') {
@@ -248,13 +447,33 @@ export default function HomeScreen() {
           setIndex(0);
           fetchNewFeed();
         }
+
+        // Widget：前台辅助刷新（尽力而为）
+        // - 写入 App Group 的 dailyReco 缓存
+        // - 生成 wrapped_text_by_family，供 Widget 直接渲染
+        ensureDailyWidgetRecoUpToDate({ reason: 'home_focus' }).catch(() => {});
       })();
       return () => {
         cancelled = true;
       };
-    }, [fetchNewFeed, recoLang, ensureSuixinReady])
+    }, [applyPendingPushItem, fetchNewFeed, recoLang, ensureSuixinReady])
   );
 
+  useEffect(() => {
+    const unsubscribe = subscribeHomePushMessage((message) => {
+      void applyPendingPushItem(message);
+    });
+    return unsubscribe;
+  }, [applyPendingPushItem]);
+
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state !== 'active') return;
+      void consumePendingPushItem();
+    });
+    return () => sub.remove();
+  }, [consumePendingPushItem]);
+
   const backgroundColor = useMemo(() => {
     if (themeMode === 'suixin') {
       return suixinBgColor;
@@ -282,24 +501,60 @@ export default function HomeScreen() {
     transform: [{ scale: likeScale.value }],
   }));
 
+  const setBusySafe = useCallback((next: boolean) => {
+    busyRef.current = next;
+    setBusy(next);
+  }, []);
+
+  const setLikeInFlight = useCallback((next: boolean) => {
+    likeInFlightRef.current = next;
+  }, []);
+
+  const syncLikeFilledByIndex = useCallback((nextIndex: number) => {
+    const list = currentFeedRef.current;
+    const len = list.length;
+    if (!len) {
+      setLikeFilled(false);
+      return;
+    }
+    const safe = ((nextIndex % len) + len) % len;
+    const nextId = String(list[safe]?.content_id);
+    setLikeFilled(likedIdsRef.current.has(nextId));
+  }, []);
+
+  const applyIndexChange = useCallback((nextIndex: number) => {
+    indexRef.current = nextIndex;
+    setIndex(nextIndex);
+    syncLikeFilledByIndex(nextIndex);
+  }, [syncLikeFilledByIndex]);
+
+  const maybeFetchNewFeedIfNeeded = useCallback((nextIndex: number) => {
+    const len = currentFeedRef.current.length;
+    if (!len) return;
+    // 当接近当前列表末尾时（例如还剩 5 条）提前拉取
+    if (nextIndex + 5 >= len && !isFetchingRef.current) {
+      fetchNewFeed();
+    }
+  }, [fetchNewFeed]);
+
   // 切换到下一条文案的统一动画逻辑
   const triggerNextContent = useCallback(() => {
-    if (busy) return;
-    setBusy(true);
+    if (busyRef.current) return;
+    setBusySafe(true);
+
+    // 注意：不要在 Reanimated worklet 回调里读取 React ref（例如 indexRef/currentFeedRef），会导致值不更新或异常
+    const nextIndex = indexRef.current + 1;
 
     // 1. 当前文案向上移动并消失
     translateY.value = withTiming(-40, { duration: 300, easing: Easing.out(Easing.quad) });
     opacity.value = withTiming(0, { duration: 300 }, (finished) => {
       if (finished) {
         // 2. 切换数据索引
-        runOnJS(setIndex)(index + 1);
-        runOnJS(setLikeFilled)(false);
+        runOnJS(applyIndexChange)(nextIndex);
         runOnJS(advanceSuixinOnNextContent)();
 
-        // 检查是否需要拉取新文案（当接近当前列表末尾时，例如还剩 5 条）
-        if (index + 5 >= currentFeed.length && !isFetching) {
-          runOnJS(fetchNewFeed)();
-        }
+        // 检查是否需要拉取新文案（注意：不要把匿名函数塞进 runOnJS，可能导致原生崩溃）
+        runOnJS(maybeFetchNewFeedIfNeeded)(nextIndex);
 
         // 3. 准备下一条文案：先瞬移到下方 40pt
         translateY.value = 40;
@@ -308,20 +563,51 @@ export default function HomeScreen() {
         translateY.value = withTiming(0, { duration: 400, easing: Easing.out(Easing.back(1)) });
         opacity.value = withTiming(1, { duration: 400 }, (finished) => {
           if (finished) {
-            runOnJS(setBusy)(false);
+            runOnJS(setBusySafe)(false);
           }
         });
       }
     });
-  }, [busy, index, currentFeed.length, isFetching, fetchNewFeed, translateY, opacity]);
+  }, [applyIndexChange, setBusySafe, translateY, opacity, advanceSuixinOnNextContent, maybeFetchNewFeedIfNeeded]);
+
+  // 切换到上一条文案的统一动画逻辑（下滑触发）
+  const triggerPrevContent = useCallback(() => {
+    if (busyRef.current) return;
+    setBusySafe(true);
+
+    // 注意：同上，不要在 worklet 里读取 React ref
+    const len = currentFeedRef.current.length;
+    const raw = indexRef.current - 1;
+    const nextIndex = len ? ((raw % len) + len) % len : Math.max(0, raw);
+
+    // 1. 当前文案向下移动并消失
+    translateY.value = withTiming(40, { duration: 300, easing: Easing.out(Easing.quad) });
+    opacity.value = withTiming(0, { duration: 300 }, (finished) => {
+      if (finished) {
+        // 2. 切换数据索引（循环回退）
+        runOnJS(applyIndexChange)(nextIndex);
+
+        // 3. 准备上一条文案：先瞬移到上方 40pt
+        translateY.value = -40;
+
+        // 4. 上一条文案向下移动到原位并显现
+        translateY.value = withTiming(0, { duration: 400, easing: Easing.out(Easing.back(1)) });
+        opacity.value = withTiming(1, { duration: 400 }, (finished) => {
+          if (finished) {
+            runOnJS(setBusySafe)(false);
+          }
+        });
+      }
+    });
+  }, [applyIndexChange, setBusySafe, translateY, opacity]);
 
   const lastTapRef = useRef<number>(0);
   
   // 使用 Ref 解决 PanResponder 闭包陷阱，确保手势回调能拿到最新的 state 和 function
-  const handlersRef = useRef({ onPressLike, triggerNextContent });
+  const handlersRef = useRef({ onPressLike, triggerNextContent, triggerPrevContent });
   useEffect(() => {
-    handlersRef.current = { onPressLike, triggerNextContent };
-  }, [onPressLike, triggerNextContent]);
+    handlersRef.current = { onPressLike, triggerNextContent, triggerPrevContent };
+  }, [onPressLike, triggerNextContent, triggerPrevContent]);
 
   // 使用系统自带的 PanResponder 代替第三方手势库
   const panResponder = useRef(
@@ -346,16 +632,32 @@ export default function HomeScreen() {
         }
         lastTapRef.current = now;
 
-        // 2. 上滑逻辑判定
+        // 2. 上滑/下滑逻辑判定
         if (gestureState.dy < -50) { // 上滑超过 50pt
           runOnJS(handlersRef.current.triggerNextContent)();
+        } else if (gestureState.dy > 50) { // 下滑超过 50pt
+          runOnJS(handlersRef.current.triggerPrevContent)();
         }
       },
     })
   ).current;
 
   async function onPressLike() {
-    if (busy) return;
+    if (busyRef.current) return;
+    if (likeInFlightRef.current) return;
+
+    // 已经喜欢过：不重复写入收藏，直接当作“下一条”
+    if (likeFilled || likedIdsRef.current.has(item.id)) {
+      triggerNextContent();
+      return;
+    }
+
+    likeInFlightRef.current = true;
+
+    const likedItemId = item.id;
+    const likedItemText = item.text;
+    // 先记下“已喜欢”，保证回退时能恢复点亮状态（即便异步保存稍后才完成）
+    likedIdsRef.current.add(likedItemId);
     setLikeFilled(true);
     
     // 1. 获取当前日期
@@ -365,24 +667,33 @@ export default function HomeScreen() {
     // 2. 保存到收藏夹，包含当前背景信息
     const favItem = {
       favId: String(Date.now()), // 生成唯一 ID
-      id: item.id,
-      text: item.text,
+      id: likedItemId,
+      text: likedItemText,
       date: dateStr,
       themeMode: themeMode,
       background: themeMode === 'scenery' ? String(natureImageIndex) : backgroundColor,
     };
     console.log('Home: Triggering addFavorite', JSON.stringify(favItem));
-    await addFavorite(favItem);
+    try {
+      await addFavorite(favItem);
+    } catch (error) {
+      console.error('Home: addFavorite 失败', error);
+    }
 
     // 3. 记录到后端 Reaction（喜欢）
     console.log('Home: Triggering setReaction', item.id);
-    await setReaction(item.id, 'like');
+    try {
+      await setReaction(item.id, 'like');
+    } catch (error) {
+      console.error('Home: setReaction 失败', error);
+    }
 
     // 4. 爱心缩放动画
     likeScale.value = withSequence(
       withTiming(0.8, { duration: 100 }),
       withTiming(1.2, { duration: 150 }),
       withTiming(1, { duration: 100 }, (finished) => {
+        runOnJS(setLikeInFlight)(false);
         if (finished) {
           console.log('Home: Like animation finished, triggering next content');
           runOnJS(triggerNextContent)();
@@ -404,6 +715,10 @@ export default function HomeScreen() {
     }
   }
 
+  const actionsBottom = isTablet
+    ? Math.max(insets.bottom + 36, Math.min(windowHeight * 0.12, 140))
+    : windowHeight * 0.16;
+
   return (
     <View style={[styles.container, { backgroundColor }]} {...panResponder.panHandlers}>
       {themeMode === 'scenery' && (
@@ -415,42 +730,59 @@ export default function HomeScreen() {
       )}
 
       {/* 自绘顶部按钮：不使用系统 Header，彻底避免 iOS 导航栏的毛玻璃/液玻璃材质 */}
-      <View style={[styles.topRight, { top: insets.top + 8 }]}>
+      <View
+        style={[
+          styles.topRight,
+          {
+            top: insets.top + (isTablet ? 16 : 8),
+            right: isTablet ? 26 : 20,
+          },
+        ]}
+      >
         <CircleIconButton
           onPress={() => setThemeOpen(true)}
           accessibilityLabel={t('home.theme')}
         >
-          <ThemeIcon width={18} height={18} />
+          <ThemeIcon width={20} height={20} />
         </CircleIconButton>
         <CircleIconButton
           onPress={() => setProfileOpen(true)}
           accessibilityLabel={t('home.profile')}
         >
-          <MyIcon width={18} height={18} />
+          <MyIcon width={20} height={20} />
         </CircleIconButton>
       </View>
 
       <Animated.View style={[styles.card, textAnimatedStyle, themeMode === 'scenery' && styles.sceneryCard]}>
-        <Text style={[styles.text, isEnglish && styles.textEnglish, themeMode === 'scenery' && styles.sceneryText]}>
-          {item.text}
-        </Text>
+        <View
+          style={[styles.textMeasureBox, isTablet && styles.textMeasureBoxTablet]}
+          onLayout={(e) => {
+            const w = e.nativeEvent.layout.width;
+            if (Number.isFinite(w) && w > 0) setCardWidth(w);
+          }}
+        >
+          <Text style={[styles.text, isEnglish && styles.textEnglish, themeMode === 'scenery' && styles.sceneryText]}>
+            {wrappedText || item.text}
+          </Text>
+        </View>
       </Animated.View>
 
-      <View style={styles.actions}>
+      <View style={[styles.actions, { bottom: actionsBottom }]}>
         <Animated.View style={[styles.reactionButton, likeAnimatedStyle]}>
           <Pressable
             onPress={onPressLike}
             accessibilityRole="button"
             accessibilityLabel={t('home.like')}
-            hitSlop={20}
+            // 稍微增大可点击区域，提升单手操作成功率
+            hitSlop={24}
             style={styles.reactionInner}
           >
             {likeFilled ? (
-              <LikeFilledIcon width={35} height={36} color="#EA6969" />
+              <LikeFilledIcon width={40} height={41} color="#EA6969" />
             ) : (
               <LikeIcon 
-                width={35} 
-                height={36} 
+                width={40} 
+                height={41} 
                 color={themeMode === 'scenery' ? '#FFFFFF' : '#5E2A28'}
               />
             )}
@@ -480,7 +812,8 @@ function CircleIconButton({
   return (
     <Pressable
       onPress={onPress}
-      hitSlop={10}
+      // 稍微增大可点击区域，提升易用性
+      hitSlop={14}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       style={styles.circleBtn}
@@ -499,15 +832,14 @@ const styles = StyleSheet.create({
   },
   topRight: {
     position: 'absolute',
-    right: 20,
     flexDirection: 'row',
     gap: 10,
     zIndex: 30,
   },
   circleBtn: {
-    width: 34,
-    height: 34,
-    borderRadius: 17,
+    width: 40,
+    height: 40,
+    borderRadius: 20,
     backgroundColor: 'rgba(255,255,255,0.75)',
     alignItems: 'center',
     justifyContent: 'center',
@@ -524,16 +856,23 @@ const styles = StyleSheet.create({
     zIndex: 5, // 降低层级，防止遮挡底部按钮
   },
   text: {
-    fontSize: 22,
-    lineHeight: 32,
+    fontSize: 24,
+    lineHeight: 34,
     color: '#5E2A28',
-    fontWeight: '700',
+    fontWeight: '800',
     textAlign: 'center',
   },
+  textMeasureBox: {
+    width: '100%',
+    alignItems: 'center',
+  },
+  textMeasureBoxTablet: {
+    maxWidth: 760,
+  },
   textEnglish: {
     fontFamily: 'STIXTwoText',
-    // 英文字体观感更细一点，避免过粗
-    fontWeight: '600',
+    // 英文字体保持较粗但避免过度发黑
+    fontWeight: '700',
   },
   sceneryCard: {
     // 风景模式下稍微收窄文案宽度，增加呼吸感
@@ -547,7 +886,6 @@ const styles = StyleSheet.create({
   },
   actions: {
     position: 'absolute',
-    bottom: SCREEN_HEIGHT * 0.16,
     left: 0,
     right: 0,
     flexDirection: 'row',

client/app/(app)/settings.tsx

@@ -1,9 +1,13 @@
 import Constants from 'expo-constants';
-import { StyleSheet, Text, View } from 'react-native';
+import { Platform, StyleSheet, Text, View, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
+import { clampContentWidth, isIPadLike } from '@/src/utils/device';
 
 export default function SettingsScreen() {
   const { t } = useTranslation();
+  const { width, height } = useWindowDimensions();
+  const isTablet = isIPadLike(width, height);
+  const contentWidth = isTablet ? clampContentWidth(width, 720, 24) : undefined;
 
   const version =
     Constants.expoConfig?.version ??
@@ -12,6 +16,7 @@ export default function SettingsScreen() {
 
   return (
     <View style={styles.container}>
+      <View style={[styles.contentWrap, contentWidth ? { width: contentWidth } : null]}>
       <View style={styles.section}>
         <Text style={styles.label}>{t('settings.version')}</Text>
         <Text style={styles.value}>{version}</Text>
@@ -21,12 +26,18 @@ export default function SettingsScreen() {
         <Text style={styles.cardTitle}>{t('settings.widgetTitle')}</Text>
         <Text style={styles.cardText}>{t('settings.widgetDesc')}</Text>
       </View>
+      </View>
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  container: { flex: 1, padding: 16, gap: 16 },
+  container: { flex: 1, width: '100%', alignSelf: 'stretch', padding: 16 },
+  contentWrap: {
+    width: '100%',
+    alignSelf: 'center',
+    gap: 16,
+  },
   section: {
     borderRadius: 14,
     padding: 16,
@@ -38,7 +49,12 @@ const styles = StyleSheet.create({
     justifyContent: 'space-between',
   },
   label: { color: '#374151', fontSize: 16 },
-  value: { color: '#111827', fontSize: 16, fontWeight: '600' },
+  value: {
+    color: '#111827',
+    fontSize: 16,
+    fontWeight: '600',
+    fontFamily: Platform.OS === 'ios' ? 'STIX Two Text' : undefined,
+  },
   card: {
     borderRadius: 16,
     padding: 16,

client/app/(onboarding)/onboarding.tsx

@@ -12,7 +12,7 @@ import { buildUserProfileFromQuestionnaire, mapOnboardingSelectionsToQuestionnai
 import { ensureDailyWidgetRecoUpToDate, syncWidgetConfig, syncWidgetUserProfileFromScoring } from '@/src/modules/dailyWidgetReco';
 import { toBackendLocaleFromLanguageTag } from '@/src/i18n/locale';
 import { fetchRecoFeed } from '@/src/services/recoApi';
-import { getExpoPushTokenOrThrow, registerPushToken, setPushPreferences } from '@/src/services/pushApi';
+import { ensurePushTokenRegisteredIfPermitted, setPushPreferences } from '@/src/services/pushApi';
 import {
   recordRecoFeedServed,
   setOnboardingCompleted,
@@ -44,6 +44,7 @@ export default function OnboardingScreen() {
   const [name, setName] = useState('');
   const [selections, setSelections] = useState<Record<string, string[]>>({});
   const [reminderTimes, setReminderTimes] = useState(3);
+  const [finishing, setFinishing] = useState(false);
 
   const currentStep = STEPS[stepIndex];
   const currentTitle = useMemo(() => t(`onboardingSurvey.steps.${currentStep.id}.title`), [t, currentStep.id]);
@@ -56,6 +57,9 @@ export default function OnboardingScreen() {
   }, [t, currentStep]);
 
   async function onFinish() {
+    if (finishing) return;
+    setFinishing(true);
+    try {
     // 用户选择每日次数 > 0：在此页直接触发系统通知权限（已移除单独的 push 引导页）。
     const wantsPush = reminderTimes > 0;
 
@@ -124,7 +128,8 @@ export default function OnboardingScreen() {
     await setPushPromptState('unknown');
     try {
       const { status } = await Notifications.requestPermissionsAsync();
-      if (status !== 'granted') {
+      // iOS 可能出现 provisional（临时授权），也应视为“已授权”
+      if (status !== 'granted' && status !== ('provisional' as any)) {
         await setPushPromptState('skipped');
         return;
       }
@@ -136,10 +141,8 @@ export default function OnboardingScreen() {
         return;
       }
 
-      // 1) 获取 Expo Push Token（失败才认为“推送开启失败”）
-      const expoPushToken = await getExpoPushTokenOrThrow();
-      // 2) 上报 token 到后端（幂等；失败才认为“推送开启失败”）
-      await registerPushToken({ pushToken: expoPushToken });
+      // 1) 上报 token 到后端（幂等；失败才认为“推送开启失败”）
+      await ensurePushTokenRegisteredIfPermitted();
 
       // 3) 上报推送偏好（幂等）
       // 注意：这一步失败时，后端仍可能已成功接收 token。
@@ -159,9 +162,17 @@ export default function OnboardingScreen() {
     } finally {
       router.replace('/(app)/home');
     }
+    } catch (e) {
+      // 极端情况下（例如本地存储/初始化异常）避免卡死在 loading：提示并允许用户重试
+      const msg = e instanceof Error ? e.message : String(e);
+      console.warn('[OnboardingFinish] 异常：', msg);
+      Alert.alert(t('push.errorTitle'), t('push.errorDesc'));
+      setFinishing(false);
+    }
   }
 
   const onNext = () => {
+    if (finishing) return;
     if (stepIndex < STEPS.length - 1) {
       setStepIndex(stepIndex + 1);
     } else {
@@ -170,6 +181,7 @@ export default function OnboardingScreen() {
   };
 
   const onBack = () => {
+    if (finishing) return;
     if (stepIndex > 0) {
       setStepIndex(stepIndex - 1);
     }
@@ -177,6 +189,7 @@ export default function OnboardingScreen() {
 
   /** 只跳過當前這一步（不填/不選當前題，進入下一步） */
   const handleSkipCurrentStep = () => {
+    if (finishing) return;
     if (currentStep.type === 'name') {
       onNext();
     } else if (currentStep.type === 'selection') {
@@ -200,6 +213,7 @@ export default function OnboardingScreen() {
   };
 
   const handleSkipStep = () => {
+    if (finishing) return;
     setSelections((prev) => ({ ...prev, [currentStep.id]: [] }));
     onNext();
   };
@@ -236,6 +250,7 @@ export default function OnboardingScreen() {
           value={Math.max(1, reminderTimes)}
           onChange={setReminderTimes}
           onFinish={onFinish}
+          loading={finishing}
           onSkip={() => {
             // 跳过每日提醒：视为 0 次（关闭）
             setReminderTimes(0);

client/app/(splash)/splash.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef, useState } from 'react';
-import { View, Text, StyleSheet, TouchableOpacity, Dimensions, Platform, Alert, Image } from 'react-native';
+import { View, Text, StyleSheet, TouchableOpacity, Platform, Alert, Image, useWindowDimensions } from 'react-native';
 import { useRouter } from 'expo-router';
 import * as WebBrowser from 'expo-web-browser';
 import { Trans, useTranslation } from 'react-i18next';
@@ -14,8 +14,6 @@ import { isTraditionalChineseLocaleTag } from '@/src/i18n/locale';
 import FlowersBg from '../../assets/images/index/flowers_endbg.svg';
 import WelcomeBtn from '../../assets/images/index/welcome_btn.svg';
 
-const { width, height } = Dimensions.get('window');
-
 // 繁中開屏 consent 文案：寫死在元件內，避免 Metro/iOS bundle 快取導致永遠顯示舊文案。
 // 若需修改，請改這裡並同步 client/src/i18n/locales/zh-TW.json 的 consent 區塊。
 const ZH_TW_CONSENT = {
@@ -27,7 +25,9 @@ const ZH_TW_CONSENT = {
 export default function SplashScreen() {
   const router = useRouter();
   const { t, i18n } = useTranslation();
+  const { width, height } = useWindowDimensions();
   const [showConsent, setShowConsent] = useState(false);
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
 
   // 繁中時強制使用上方常數（含 zh-TW / zh-Hant / zh-Hant-TW），其餘用 i18n
   const isZhTW = isTraditionalChineseLocaleTag(i18n.language || '');
@@ -127,52 +127,67 @@ export default function SplashScreen() {
     void refreshLegalLinks();
   }, []);
 
-  const bgDecorationTop = 363;
-  const bgDecorationHeight = height * 0.6;
+  const bgDecorationHeight = isTablet ? Math.round(height * 0.55) : height * 0.6;
+  const bgDecorationTop = height - bgDecorationHeight;
   const contentTop = bgDecorationTop + (bgDecorationHeight * 0.25);
+  const contentWidth = isTablet ? Math.min(640, Math.floor(width * 0.76)) : width;
+  const topImageWidth = isTablet ? Math.min(430, Math.floor(width * 0.48)) : 308;
+  const topImageHeight = isTablet ? Math.min(460, Math.floor(height * 0.45)) : 354;
+  const topImageMarginTop = isTablet ? 148 : 60;
+  const bgWidth = width + 10;
+  const bgLeft = -3;
+  const buttonSize = isTablet ? { width: 108, height: 70 } : { width: 87, height: 57 };
+  const bottomOffset = isTablet ? 28 : 60;
+  const buttonBottomGap = isTablet ? 28 : 40;
+  const noticeStyle = isTablet
+    ? { fontSize: 14, lineHeight: 20, paddingHorizontal: 32, maxWidth: contentWidth }
+    : null;
+  const noticeLinkStyle = isTablet ? { fontSize: 14 } : null;
+  const titleStyle = isTablet ? { fontSize: 50, lineHeight: 60 } : null;
+  const subtitleStyle = isTablet ? { marginTop: 10, fontSize: 18, lineHeight: 24 } : null;
 
   return (
     <View style={styles.container}>
       {/* 中间的背景装饰 SVG (现在放在上面，作为上层) */}
-      <View style={[styles.bgDecorationContainer, { top: bgDecorationTop }]}>
-        <FlowersBg width={width + 10} height={bgDecorationHeight} />
+      <View style={[styles.bgDecorationContainer, { bottom: 0, left: bgLeft }]}>
+        <FlowersBg width={bgWidth} height={bgDecorationHeight} preserveAspectRatio="none" />
       </View>
 
       {/* 顶部的花图片 (现在放在下面，作为下层) */}
-      <View style={styles.topImageContainer}>
+      <View style={[styles.topImageContainer, { marginTop: topImageMarginTop }]}>
         <Image
           source={require('../../assets/images/index/index_flowers.png')}
-          style={styles.topImage}
+          style={[styles.topImage, { width: topImageWidth, height: topImageHeight }]}
           resizeMode="contain"
         />
       </View>
 
       {/* 文案内容：主標題兩行 + 可選二級標題（字號更小、顏色更淺）；繁中為元件內常數，其餘用 i18n */}
-      <View style={[styles.contentContainer, { position: 'absolute', top: contentTop }]}>
-        <Text style={styles.titleText}>
+      <View style={[styles.contentContainer, { position: 'absolute', top: contentTop, width: contentWidth }]}>
+        <Text style={[styles.titleText, titleStyle]}>
           {title}
           {'\n'}
           {subtitle}
         </Text>
         {subtitleSecondary ? (
-          <Text style={styles.consentSubtitleSecondary}>{subtitleSecondary}</Text>
+          <Text style={[styles.consentSubtitleSecondary, subtitleStyle]}>{subtitleSecondary}</Text>
         ) : null}
       </View>
 
-      <SafeAreaView style={styles.bottomContainer} edges={['bottom']}>
+      <SafeAreaView style={[styles.bottomContainer, { bottom: bottomOffset, width: contentWidth }]} edges={['bottom']}>
         {showConsent && (
           <>
             <TouchableOpacity
               onPress={handleAgree}
               activeOpacity={0.8}
-              style={styles.buttonWrapper}
+              style={[styles.buttonWrapper, { marginBottom: buttonBottomGap }]}
               accessibilityRole="button"
               accessibilityLabel={t('consent.agree')}
             >
-              <WelcomeBtn width={87} height={57} />
+              <WelcomeBtn width={buttonSize.width} height={buttonSize.height} />
             </TouchableOpacity>
 
-            <Text style={styles.noticeText}>
+            <Text style={[styles.noticeText, noticeStyle]}>
               <Trans
                 i18nKey="consent.noticeRich"
                 values={{
@@ -184,14 +199,14 @@ export default function SplashScreen() {
                 components={{
                   privacy: (
                     <Text
-                      style={[styles.noticeLinkText, !links.privacy && styles.noticeLinkTextDisabled]}
+                      style={[styles.noticeLinkText, noticeLinkStyle, !links.privacy && styles.noticeLinkTextDisabled]}
                       onPress={() => void handleOpenLegal('privacy')}
                       suppressHighlighting
                     />
                   ),
                   terms: (
                     <Text
-                      style={[styles.noticeLinkText, !links.terms && styles.noticeLinkTextDisabled]}
+                      style={[styles.noticeLinkText, noticeLinkStyle, !links.terms && styles.noticeLinkTextDisabled]}
                       onPress={() => void handleOpenLegal('terms')}
                       suppressHighlighting
                     />
@@ -209,11 +224,13 @@ export default function SplashScreen() {
 const styles = StyleSheet.create({
   container: {
     flex: 1,
+    width: '100%',
+    height: '100%',
+    alignSelf: 'stretch',
     backgroundColor: '#F5D3B5', // 匹配 Figma 背景色
     alignItems: 'center',
   },
   topImageContainer: {
-    marginTop: 60,
     zIndex: 1, // 降低层级
   },
   topImage: {
@@ -222,7 +239,6 @@ const styles = StyleSheet.create({
   },
   bgDecorationContainer: {
     position: 'absolute',
-    left: -3,
     zIndex: 2, // 提高层级，使其覆盖在图片之上
   },
   contentContainer: {
@@ -247,8 +263,6 @@ const styles = StyleSheet.create({
   },
   bottomContainer: {
     position: 'absolute',
-    bottom: 60,
-    width: '100%',
     alignItems: 'center',
     zIndex: 4,
   },

client/app/+not-found.tsx

@@ -1,18 +1,25 @@
 import { Link, Stack } from 'expo-router';
-import { StyleSheet } from 'react-native';
+import { StyleSheet, useWindowDimensions } from 'react-native';
 
 import { Text, View } from '@/components/Themed';
+import { clampContentWidth, isIPadLike } from '@/src/utils/device';
 
 export default function NotFoundScreen() {
+  const { width, height } = useWindowDimensions();
+  const isTablet = isIPadLike(width, height);
+  const contentWidth = isTablet ? clampContentWidth(width, 680, 24) : undefined;
+
   return (
     <>
       <Stack.Screen options={{ title: 'Oops!' }} />
       <View style={styles.container}>
-        <Text style={styles.title}>This screen doesn't exist.</Text>
+        <View style={[styles.contentWrap, contentWidth ? { width: contentWidth } : null]}>
+          <Text style={styles.title}>This screen doesn't exist.</Text>
 
-        <Link href="/" style={styles.link}>
-          <Text style={styles.linkText}>Go to home screen!</Text>
-        </Link>
+          <Link href="/" style={styles.link}>
+            <Text style={styles.linkText}>Go to home screen!</Text>
+          </Link>
+        </View>
       </View>
     </>
   );
@@ -24,6 +31,12 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
     padding: 20,
+    width: '100%',
+    alignSelf: 'stretch',
+  },
+  contentWrap: {
+    width: '100%',
+    alignItems: 'center',
   },
   title: {
     fontSize: 20,

client/app/_layout.tsx

@@ -1,7 +1,7 @@
 import FontAwesome from '@expo/vector-icons/FontAwesome';
 import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
 import { useFonts } from 'expo-font';
-import { Stack } from 'expo-router';
+import { Stack, useRouter } from 'expo-router';
 import * as SplashScreen from 'expo-splash-screen';
 import * as Notifications from 'expo-notifications';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -11,7 +11,9 @@ import { Animated, AppState, Image, StyleSheet, View } from 'react-native';
 import { useColorScheme } from '@/components/useColorScheme';
 import { initI18n } from '@/src/i18n';
 import { ensureDailyWidgetRecoUpToDate, syncWidgetConfig, syncWidgetUserProfileFromStorage } from '@/src/modules/dailyWidgetReco';
-import { getOrCreateClientUserId } from '@/src/storage/appStorage';
+import { getConsentAccepted, getOnboardingCompleted, getOrCreateClientUserId } from '@/src/storage/appStorage';
+import { persistHomePushMessageFromResponse } from '@/src/services/pushNotificationRoute';
+import { ensurePushTokenRegisteredIfPermitted } from '@/src/services/pushApi';
 
 // 配置通知处理方式（即使不发送也建议配置，以确保权限接口正常）
 Notifications.setNotificationHandler({
@@ -75,6 +77,28 @@ export default function RootLayout() {
       });
   }, []);
 
+  useEffect(() => {
+    // 只要系统通知权限已经 granted，就主动上报 Push Token（不依赖用户在“每日提醒”里点确认）
+    ensurePushTokenRegisteredIfPermitted()
+      .then((res) => {
+        if (__DEV__) console.log('[push_token_sync]', res);
+      })
+      .catch((e) => {
+        if (__DEV__) console.warn('[push_token_sync] 失败（不阻塞启动）', e);
+      });
+  }, []);
+
+  useEffect(() => {
+    // 兜底：当用户在系统弹窗/系统设置里变更权限后，App 回到前台时再同步一次 token
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state !== 'active') return;
+      ensurePushTokenRegisteredIfPermitted().catch(() => {
+        // ignore：不阻塞
+      });
+    });
+    return () => sub.remove();
+  }, []);
+
   useEffect(() => {
     // 字体与 i18n 都准备好后，允许渲染 App（原生 splash 的隐藏交给 onLayout，避免“硬切/闪白”）
     if (loaded && i18nReady) setAppReady(true);
@@ -113,7 +137,7 @@ export default function RootLayout() {
         <Animated.View pointerEvents="none" style={[StyleSheet.absoluteFill, { opacity: splashOpacity }]}>
           <View style={styles.splashOverlay}>
             <Image
-              source={require('../assets/images/splashScreen.png')}
+              source={require('../assets/images/Screen_page.png')}
               style={styles.splashImage}
               resizeMode="contain"
             />
@@ -126,6 +150,7 @@ export default function RootLayout() {
 
 function RootLayoutNav() {
   const colorScheme = useColorScheme();
+  const router = useRouter();
 
   useEffect(() => {
     // iOS 小组件：启动时把必要信息写入共享区，并尽力刷新一次“每日推荐”
@@ -142,6 +167,44 @@ function RootLayoutNav() {
     return () => sub.remove();
   }, []);
 
+  const handleNotificationResponse = useCallback(
+    async (response: Notifications.NotificationResponse) => {
+      const message = await persistHomePushMessageFromResponse(response);
+      if (!message) return;
+
+      const [consentAccepted, onboardingCompleted] = await Promise.all([
+        getConsentAccepted(),
+        getOnboardingCompleted(),
+      ]);
+      if (consentAccepted && onboardingCompleted) {
+        router.replace('/(app)/home');
+      }
+    },
+    [router]
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+
+    Notifications.getLastNotificationResponseAsync()
+      .then((response) => {
+        if (cancelled || !response) return;
+        return handleNotificationResponse(response);
+      })
+      .catch(() => {
+        // ignore：通知冷启动读取失败不阻塞主流程
+      });
+
+    const sub = Notifications.addNotificationResponseReceivedListener((response) => {
+      void handleNotificationResponse(response);
+    });
+
+    return () => {
+      cancelled = true;
+      sub.remove();
+    };
+  }, [handleNotificationResponse]);
+
   return (
     <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
       <Stack screenOptions={{ headerShown: false }}>

client/app/index.tsx

@@ -1,14 +1,18 @@
 import { useEffect } from 'react';
-import { ActivityIndicator, StyleSheet, View } from 'react-native';
+import { ActivityIndicator, StyleSheet, View, useWindowDimensions } from 'react-native';
 import { useRouter } from 'expo-router';
 
 import { getOnboardingCompleted, getConsentAccepted } from '@/src/storage/appStorage';
+import { clampContentWidth, isIPadLike } from '@/src/utils/device';
 
 /**
  * 启动分发：根据 consent 和 onboarding 状态跳转
  */
 export default function Index() {
   const router = useRouter();
+  const { width, height } = useWindowDimensions();
+  const isTablet = isIPadLike(width, height);
+  const loaderWidth = isTablet ? clampContentWidth(width, 680, 24) : undefined;
 
   useEffect(() => {
     let cancelled = false;
@@ -41,11 +45,24 @@ export default function Index() {
 
   return (
     <View style={styles.container}>
-      <ActivityIndicator />
+      <View style={[styles.loaderWrap, loaderWidth ? { width: loaderWidth } : null]}>
+        <ActivityIndicator />
+      </View>
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  container: { flex: 1, alignItems: 'center', justifyContent: 'center' },
+  container: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+    alignSelf: 'stretch',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  loaderWrap: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
 });

client/app/modal.tsx

@@ -1,15 +1,22 @@
 import { StatusBar } from 'expo-status-bar';
-import { Platform, StyleSheet } from 'react-native';
+import { Platform, StyleSheet, useWindowDimensions } from 'react-native';
 
 import EditScreenInfo from '@/components/EditScreenInfo';
 import { Text, View } from '@/components/Themed';
+import { clampContentWidth, isIPadLike } from '@/src/utils/device';
 
 export default function ModalScreen() {
+  const { width, height } = useWindowDimensions();
+  const isTablet = isIPadLike(width, height);
+  const contentWidth = isTablet ? clampContentWidth(width, 700, 24) : undefined;
+
   return (
     <View style={styles.container}>
-      <Text style={styles.title}>Modal</Text>
-      <View style={styles.separator} lightColor="#eee" darkColor="rgba(255,255,255,0.1)" />
-      <EditScreenInfo path="app/modal.tsx" />
+      <View style={[styles.contentWrap, contentWidth ? { width: contentWidth } : null]}>
+        <Text style={styles.title}>Modal</Text>
+        <View style={styles.separator} lightColor="#eee" darkColor="rgba(255,255,255,0.1)" />
+        <EditScreenInfo path="app/modal.tsx" />
+      </View>
 
       {/* Use a light status bar on iOS to account for the black space above the modal */}
       <StatusBar style={Platform.OS === 'ios' ? 'light' : 'auto'} />
@@ -22,6 +29,12 @@ const styles = StyleSheet.create({
     flex: 1,
     alignItems: 'center',
     justifyContent: 'center',
+    width: '100%',
+    alignSelf: 'stretch',
+  },
+  contentWrap: {
+    width: '100%',
+    alignItems: 'center',
   },
   title: {
     fontSize: 20,

client/components/home/ProfileModal.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState, useRef, useCallback } from 'react';
-import { Alert, FlatList, Image, Pressable, StyleSheet, Text, View, Platform, Dimensions } from 'react-native';
+import { Alert, FlatList, Image, Pressable, StyleSheet, Text, View, Platform, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { LinearGradient } from 'expo-linear-gradient';
 import { Switch } from 'react-native';
@@ -41,9 +41,8 @@ import QuestionIcon from '@/assets/images/home/Profile/widget/question_icon.svg'
 import * as Notifications from 'expo-notifications';
 import { changeLanguage } from '@/src/i18n';
 import { fetchLegalLinks } from '@/src/services/legalApi';
-import { getExpoPushTokenOrThrow, registerPushToken, setPushPreferences } from '@/src/services/pushApi';
-
-const { width } = Dimensions.get('window');
+import { ensurePushTokenRegisteredIfPermitted, setPushPreferences } from '@/src/services/pushApi';
+import { isIPadLike } from '@/src/utils/device';
 
 type Props = {
   visible: boolean;
@@ -79,6 +78,12 @@ const NATURE_IMAGES = [
 
 export default function ProfileModal({ visible, name: propName, onClose }: Props) {
   const { t } = useTranslation();
+  const { width, height } = useWindowDimensions();
+  const isTablet = isIPadLike(width, height);
+  const contentWidth = isTablet ? width - 40 : width - 40;
+  const thumbWidth = isTablet ? Math.min(420, contentWidth - 120) : Math.min(width * 0.6, 300);
+  const widgetImageWidth = isTablet ? Math.min(520, contentWidth - 24) : width * 0.9;
+  const howToSlideWidth = isTablet ? Math.min(640, contentWidth) : width - 32;
 
   const [page, setPage] = useState<Page>('root');
   const [navDirection, setNavDirection] = useState<NavDirection>('forward');
@@ -192,6 +197,7 @@ export default function ProfileModal({ visible, name: propName, onClose }: Props
           {page === 'root' ? (
             <RootPage
               name={currentName}
+              contentWidth={contentWidth}
               onOpenFavorites={() => go('favorites', 'forward')}
               onOpenWidget={() => go('widget', 'forward')}
               onOpenDailyReminder={() => go('dailyReminder', 'forward')}
@@ -200,15 +206,15 @@ export default function ProfileModal({ visible, name: propName, onClose }: Props
               onOpenTerms={() => openLink(legalLinks.terms)}
             />
           ) : page === 'favorites' ? (
-            <FavoritesPage visible={visible} page={page} />
+            <FavoritesPage visible={visible} page={page} thumbWidth={thumbWidth} contentWidth={contentWidth} />
           ) : page === 'dailyReminder' ? (
-            <DailyReminderPage visible={visible} onDone={() => go('root', 'back')} />
+            <DailyReminderPage visible={visible} onDone={() => go('root', 'back')} contentWidth={contentWidth} />
           ) : page === 'language' ? (
-            <LanguagePage />
+            <LanguagePage contentWidth={contentWidth} />
           ) : page === 'widgetHowTo' ? (
-            <WidgetHowToPage />
+            <WidgetHowToPage howToSlideWidth={howToSlideWidth} widgetImageWidth={widgetImageWidth} />
           ) : (
-            <WidgetPage onOpenHowTo={() => go('widgetHowTo', 'forward')} />
+            <WidgetPage onOpenHowTo={() => go('widgetHowTo', 'forward')} widgetImageWidth={widgetImageWidth} />
           )}
         </Animated.View>
       </View>
@@ -222,6 +228,7 @@ function toastTodo(t: (key: string) => string) {
 
 function RootPage({
   name,
+  contentWidth,
   onOpenFavorites,
   onOpenWidget,
   onOpenDailyReminder,
@@ -230,6 +237,7 @@ function RootPage({
   onOpenTerms,
 }: {
   name?: string;
+  contentWidth: number;
   onOpenFavorites: () => void;
   onOpenWidget: () => void;
   onOpenDailyReminder: () => void;
@@ -239,7 +247,7 @@ function RootPage({
 }) {
   const { t } = useTranslation();
   return (
-    <>
+    <View style={[styles.sectionWrap, { width: contentWidth }]}>
       <View style={styles.header}>
         <AvatarIcon width={234} height={183} />
         <Text style={styles.name}>{name || 'Hali'}</Text>
@@ -276,11 +284,23 @@ function RootPage({
           onPress={onOpenLanguage}
         />
       </View>
-    </>
+
+      <Text style={styles.versionText}>V1.0.0</Text>
+    </View>
   );
 }
 
-function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
+function FavoritesPage({
+  visible,
+  page,
+  thumbWidth,
+  contentWidth,
+}: {
+  visible: boolean;
+  page: Page;
+  thumbWidth: number;
+  contentWidth: number;
+}) {
   const { t } = useTranslation();
   const [favorites, setFavorites] = useState<(FavoriteItem & { text: string })[]>([]);
 
@@ -317,7 +337,7 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
   }
 
   return (
-    <View style={styles.favContainer}>
+    <View style={[styles.favContainer, { width: contentWidth, alignSelf: 'center' }]}>
       {favorites.length === 0 ? (
         <Text style={styles.favEmpty}>{t('favorites.empty')}</Text>
       ) : (
@@ -339,6 +359,7 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
               <View style={styles.favRight}>
                 <View style={[
                   styles.favThumb, 
+                  { width: thumbWidth },
                   item.themeMode === 'scenery' ? {} : { backgroundColor: item.background }
                 ]}>
                   {item.themeMode === 'scenery' ? (
@@ -346,7 +367,7 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
                       <Image 
                         source={NATURE_IMAGES[parseInt(item.background)]} 
                         style={{
-                          width: width * 0.6,
+                          width: thumbWidth,
                           height: 800, // 假设原图较高，设置一个较大的高度
                           position: 'absolute',
                           bottom: 0, // 关键：将图片底部对齐容器底部
@@ -378,7 +399,15 @@ function FavoritesPage({ visible, page }: { visible: boolean; page: Page }) {
   );
 }
 
-function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () => void }) {
+function DailyReminderPage({
+  visible,
+  onDone,
+  contentWidth,
+}: {
+  visible: boolean;
+  onDone: () => void;
+  contentWidth: number;
+}) {
   const { t } = useTranslation();
   const [loading, setLoading] = useState(false);
   const [timesPerDay, setTimesPerDay] = useState(3);
@@ -430,14 +459,13 @@ function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () =
       // 调试：打印状态
       console.log('Push Permission Status:', status);
 
-      if (status === 'granted') {
+      if (status === 'granted' || (status as any) === 'provisional') {
         setPushEnabled(true);
         setHasSystemPermission(true);
 
         // 获取 token 并上报后端（幂等）
         try {
-          const expoPushToken = await getExpoPushTokenOrThrow();
-          await registerPushToken({ pushToken: expoPushToken });
+          await ensurePushTokenRegisteredIfPermitted();
           // 偏好同步失败不应被用户感知为“开启失败”
           // （常见现象：后端已接收 token，但偏好接口短暂失败/超时）
           try {
@@ -479,6 +507,13 @@ function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () =
     const next: DailyReminderSettings = { timesPerDay: nextTimes, pushEnabled: nextEnabled };
     await setDailyReminderSettings(next);
 
+    // 若系统权限已授予且用户意愿为开启：兜底同步一次 token（避免“没点开关/没触发 toggle 导致后端无 token”）
+    if (nextEnabled) {
+      ensurePushTokenRegisteredIfPermitted().catch(() => {
+        // ignore：不阻塞保存
+      });
+    }
+
     // 同步后端偏好（幂等；失败不阻塞）
     try {
       await setPushPreferences({ enabled: nextEnabled, timesPerDay: nextTimes });
@@ -519,7 +554,7 @@ function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () =
         </Pressable>
       </View>
 
-      <View style={styles.remindRow}>
+      <View style={[styles.remindRow, { width: contentWidth }]}>
         <View style={styles.rowLeft}>
           <View style={styles.rowIcon}>
             <RemindIcon width={18} height={18} />
@@ -550,9 +585,11 @@ function DailyReminderPage({ visible, onDone }: { visible: boolean; onDone: () =
   );
 }
 
-function WidgetPage({ onOpenHowTo }: { onOpenHowTo: () => void }) {
+function WidgetPage({ onOpenHowTo, widgetImageWidth }: { onOpenHowTo: () => void; widgetImageWidth: number }) {
   const { t, i18n } = useTranslation();
   const currentLang = i18n.language;
+  // 需求：个人主页弹窗「小工具」页暂时隐藏锁屏小工具说明/入口
+  const showLockScreenWidget = false;
 
   // 根据语言选择图片
   const widget1 = currentLang === 'en' 
@@ -570,13 +607,15 @@ function WidgetPage({ onOpenHowTo }: { onOpenHowTo: () => void }) {
       </Pressable>
 
       <View style={styles.widgetScroll}>
-        <Pressable style={styles.widgetItem} onPress={onOpenHowTo}>
-          <Image source={widget1} style={styles.widgetImg1} resizeMode="contain" />
-          <Text style={styles.widgetLabel}>{t('widget.lockScreen')}</Text>
-        </Pressable>
+        {showLockScreenWidget ? (
+          <Pressable style={styles.widgetItem} onPress={onOpenHowTo}>
+            <Image source={widget1} style={[styles.widgetImg1, { width: widgetImageWidth, height: widgetImageWidth * (156 / 311) }]} resizeMode="contain" />
+            <Text style={styles.widgetLabel}>{t('widget.lockScreen')}</Text>
+          </Pressable>
+        ) : null}
 
         <Pressable style={styles.widgetItem} onPress={onOpenHowTo}>
-          <Image source={widget2} style={styles.widgetImg2} resizeMode="contain" />
+          <Image source={widget2} style={[styles.widgetImg2, { width: widgetImageWidth, height: widgetImageWidth * (175 / 311) }]} resizeMode="contain" />
           <Text style={styles.widgetLabel}>{t('widget.homeScreen')}</Text>
         </Pressable>
       </View>
@@ -584,7 +623,7 @@ function WidgetPage({ onOpenHowTo }: { onOpenHowTo: () => void }) {
   );
 }
 
-function WidgetHowToPage() {
+function WidgetHowToPage({ howToSlideWidth, widgetImageWidth }: { howToSlideWidth: number; widgetImageWidth: number }) {
   const { t, i18n } = useTranslation();
   const currentLang = i18n.language;
   const flatListRef = useRef<FlatList>(null);
@@ -621,7 +660,7 @@ function WidgetHowToPage() {
 
   const onScroll = (event: any) => {
     const x = event.nativeEvent.contentOffset.x;
-    const index = Math.round(x / (width - 32));
+    const index = Math.round(x / howToSlideWidth);
     if (index !== activeIndex) {
       setActiveIndex(index);
     }
@@ -645,14 +684,14 @@ function WidgetHowToPage() {
         onScrollBeginDrag={onScrollBeginDrag}
         scrollEventThrottle={16}
         renderItem={({ item }) => (
-          <View style={styles.howToSlide}>
-            <Image source={item.src} style={styles.howToImg} resizeMode="contain" />
+          <View style={[styles.howToSlide, { width: howToSlideWidth }]}>
+            <Image source={item.src} style={[styles.howToImg, { width: widgetImageWidth, height: widgetImageWidth * (234 / 326) }]} resizeMode="contain" />
             <Text style={styles.howToDesc}>{item.desc}</Text>
           </View>
         )}
       />
       
-      <View style={styles.pagination}>
+      <View style={[styles.pagination, { top: widgetImageWidth * (234 / 326) + 35 }]}>
         {images.map((_, i) => (
           <View
             key={i}
@@ -667,7 +706,7 @@ function WidgetHowToPage() {
   );
 }
 
-function LanguagePage() {
+function LanguagePage({ contentWidth }: { contentWidth: number }) {
   const { t, i18n } = useTranslation();
   const currentLang = i18n.language;
 
@@ -677,8 +716,8 @@ function LanguagePage() {
   ];
 
   return (
-    <View style={styles.langPage}>
-      <View style={styles.langList}>
+    <View style={[styles.langPage, { width: contentWidth, alignSelf: 'center' }]}>
+      <View style={[styles.langList, { width: contentWidth }]}>
         {languages.map((lang, index) => (
           <Pressable
             key={lang.id}
@@ -740,6 +779,9 @@ const styles = StyleSheet.create({
   pageWrap: {
     // 给页面切换动画一个稳定的容器，避免布局抖动
   },
+  sectionWrap: {
+    alignSelf: 'center',
+  },
   backRow: {
     alignSelf: 'flex-start',
     paddingVertical: 4,
@@ -796,6 +838,13 @@ const styles = StyleSheet.create({
     overflow: 'hidden',
     marginBottom: 8,
   },
+  versionText: {
+    marginTop: 12,
+    textAlign: 'center',
+    color: 'rgba(94,42,40,0.45)',
+    fontSize: 12,
+    fontWeight: '500',
+  },
   item: {
     height: 52,
     paddingHorizontal: 18,
@@ -838,7 +887,7 @@ const styles = StyleSheet.create({
     paddingVertical: 100,
   },
   favList: {
-    paddingHorizontal: 20,
+    paddingHorizontal: 8,
     paddingBottom: 80,
   },
   favCard: {
@@ -862,7 +911,6 @@ const styles = StyleSheet.create({
     backgroundColor: '#FFF4EA',
     borderRadius: 16,
     padding: 20,
-    width: width * 0.6,
     height: 161,
     justifyContent: 'center',
     position: 'relative',
@@ -935,7 +983,6 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'space-between',
     marginBottom: 18,
-    width: width - 40, // 屏幕宽度减去左右各 20pt
     alignSelf: 'center',
   },
   rowLeft: { flexDirection: 'row', alignItems: 'center', gap: 10 },
@@ -994,12 +1041,12 @@ const styles = StyleSheet.create({
     width: '100%',
   },
   widgetImg1: {
-    width: width * 0.9,
-    height: (width * 0.9) * (156 / 311),
+    width: 320,
+    height: 160,
   },
   widgetImg2: {
-    width: width * 0.9,
-    height: (width * 0.9) * (175 / 311),
+    width: 320,
+    height: 176,
   },
   widgetLabel: {
     marginTop: 12,
@@ -1013,12 +1060,12 @@ const styles = StyleSheet.create({
     paddingTop: 20,
   },
   howToSlide: {
-    width: width - 32, // 减去 SheetModal 的 paddingHorizontal: 16 * 2
+    width: 320,
     alignItems: 'center',
   },
   howToImg: {
-    width: width * 0.9,
-    height: (width * 0.9) * (234 / 326),
+    width: 320,
+    height: 230,
     marginBottom: 40,
   },
   howToDesc: {
@@ -1032,7 +1079,7 @@ const styles = StyleSheet.create({
   pagination: {
     flexDirection: 'row',
     position: 'absolute',
-    top: (width * 0.9) * (234 / 326) + 35, // 根据新的图片高度动态计算
+    top: 265,
     gap: 8,
   },
   dot: {
@@ -1054,7 +1101,6 @@ const styles = StyleSheet.create({
     backgroundColor: '#FFFFFF',
     borderRadius: 20,
     overflow: 'hidden',
-    width: width - 40, // 屏幕宽度减去左右各 20pt
     alignSelf: 'center',
   },
   langItem: {

client/components/home/ThemeModal.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Image, Pressable, StyleSheet, Text, View } from 'react-native';
+import { Image, Pressable, StyleSheet, Text, View, Platform, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 
 import SheetModal from '@/components/ui/SheetModal';
@@ -15,8 +15,11 @@ type Props = {
 
 export default function ThemeModal({ visible, mode, onSelect, onClose }: Props) {
   const { t } = useTranslation();
+  const { width, height } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
+
   return (
-    <SheetModal visible={visible} title={t('theme.title')} onClose={onClose} height={360}>
+    <SheetModal visible={visible} title={t('theme.title')} onClose={onClose} height={isTablet ? 560 : 360}>
       <View style={styles.row}>
         <ThemeCard
           title={t('theme.scenery')}
@@ -100,9 +103,9 @@ const styles = StyleSheet.create({
   row: {
     flexDirection: 'row',
     flexWrap: 'nowrap',
-    gap: 12,
-    paddingHorizontal: 4,
-    paddingBottom: 50,
+    gap: 8,
+    paddingHorizontal: 0,
+    paddingBottom: 22,
     paddingTop: 20,
     justifyContent: 'space-between',
   },

client/components/home/WidgetModal.tsx

@@ -13,7 +13,7 @@ export default function WidgetModal({ visible, onClose }: Props) {
   const { t } = useTranslation();
 
   return (
-    <SheetModal visible={visible} title={t('profile.widget')} onClose={onClose}>
+    <SheetModal visible={visible} title={t('widget.howToTitle')} onClose={onClose}>
       <View style={styles.content}>
         <View style={styles.row}>
           <PreviewCard label={t('widget.lockScreen')}>

client/components/onboarding/NameInputStep.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { View, StyleSheet, TextInput, Platform, Animated, TouchableOpacity, Text, Keyboard, Pressable } from 'react-native';
+import { View, StyleSheet, TextInput, Platform, Animated, TouchableOpacity, Text, Keyboard, Pressable, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { OnboardingColors } from '@/constants/OnboardingTheme';
@@ -16,10 +16,13 @@ interface NameInputStepProps {
 export function NameInputStep({ value, onChangeText, onNext }: NameInputStepProps) {
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
+  const { width, height } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
   const [isFocused, setIsFocused] = useState(false);
   const [keyboardHeight, setKeyboardHeight] = useState(0);
   const blinkAnim = useRef(new Animated.Value(1)).current;
   const hasInput = value.trim().length > 0;
+  const inputCardWidth = isTablet ? Math.min(520, Math.floor(width * 0.72)) : 335;
 
   useEffect(() => {
     const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
@@ -62,7 +65,7 @@ export function NameInputStep({ value, onChangeText, onNext }: NameInputStepProp
 
   return (
     <Pressable style={styles.container} onPress={Keyboard.dismiss} accessible={false}>
-      <View style={styles.inputCard}>
+      <View style={[styles.inputCard, { width: inputCardWidth }]}>
         <View style={styles.inputWrapper}>
           {/* 显示层：文案 + 跟随的光标 */}
           <View style={styles.displayLayer}>

client/components/onboarding/OnboardingLayout.tsx

@@ -1,5 +1,5 @@
 import React, { useRef, useEffect } from 'react';
-import { View, StyleSheet, SafeAreaView, TouchableOpacity, StatusBar, Text, Image, Platform, Animated, Easing } from 'react-native';
+import { View, StyleSheet, SafeAreaView, TouchableOpacity, StatusBar, Text, Image, Platform, Animated, Easing, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { OnboardingColors, OnboardingFont } from '@/constants/OnboardingTheme';
 
@@ -29,6 +29,9 @@ export function OnboardingLayout({
   userName = '',
 }: OnboardingLayoutProps) {
   const { t } = useTranslation();
+  const { width, height } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
+  const contentMaxWidth = isTablet ? 620 : undefined;
   const showGreeting = currentStep === 1 && userName.trim().length > 0;
   const displayName = userName.trim();
   const prevStepRef = useRef(currentStep);
@@ -72,7 +75,7 @@ export function OnboardingLayout({
       <StatusBar barStyle="dark-content" />
       <SafeAreaView style={styles.safeArea}>
         {/* Header: Back & Skip */}
-        <View style={styles.header}>
+        <View style={[styles.header, contentMaxWidth ? { maxWidth: contentMaxWidth, width: '100%', alignSelf: 'center' } : null]}>
           <View style={styles.headerLeft}>
             {showBackButton && onBack && (
               <TouchableOpacity onPress={onBack} style={styles.iconButton}>
@@ -94,7 +97,7 @@ export function OnboardingLayout({
         </View>
 
         {/* Title & Progress Row（名字步骤后第一步且名字非空时显示招呼语 + 问题） */}
-        <View style={styles.titleRow}>
+        <View style={[styles.titleRow, contentMaxWidth ? { maxWidth: contentMaxWidth, width: '100%', alignSelf: 'center' } : null]}>
           <View style={styles.titleBlock}>
             {showGreeting && (
               <Text style={styles.greetingText}>{t('onboardingSurvey.greeting', { name: displayName })}</Text>
@@ -108,6 +111,7 @@ export function OnboardingLayout({
         <Animated.View
           style={[
             styles.content,
+            contentMaxWidth ? { maxWidth: contentMaxWidth, width: '100%', alignSelf: 'center' } : null,
             {
               opacity,
               transform: [{ translateX }],

client/components/onboarding/ReminderStep.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
-import { View, StyleSheet, TouchableOpacity, Text, Platform } from 'react-native';
+import { View, StyleSheet, TouchableOpacity, Text, Platform, ActivityIndicator, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { LinearGradient } from 'expo-linear-gradient';
 import { OnboardingColors } from '@/constants/OnboardingTheme';
 import AddIcon from '@/assets/images/icon/add_icon.svg';
 import ReduceIcon from '@/assets/images/icon/reduce_icon.svg';
@@ -12,11 +13,16 @@ interface ReminderStepProps {
   onChange: (value: number) => void;
   onFinish: () => void;
   onSkip?: () => void;
+  /** 完成后请求通知权限时的加载态 */
+  loading?: boolean;
 }
 
-export function ReminderStep({ value, onChange, onFinish }: ReminderStepProps) {
+export function ReminderStep({ value, onChange, onFinish, loading = false }: ReminderStepProps) {
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
+  const { width, height } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
+  const contentMaxWidth = isTablet ? 560 : undefined;
 
   const handleReduce = () => {
     // 本页最小为 1；不接收提醒请使用右上角 Skip
@@ -29,8 +35,8 @@ export function ReminderStep({ value, onChange, onFinish }: ReminderStepProps) {
 
   return (
     <View style={styles.container}>
-      <View style={styles.counterContainer}>
-        <TouchableOpacity onPress={handleReduce} activeOpacity={0.7}>
+      <View style={[styles.counterContainer, contentMaxWidth ? { maxWidth: contentMaxWidth } : null]}>
+        <TouchableOpacity onPress={handleReduce} disabled={loading} activeOpacity={0.7}>
           <ReduceIcon width={47} height={47} />
         </TouchableOpacity>
 
@@ -41,14 +47,27 @@ export function ReminderStep({ value, onChange, onFinish }: ReminderStepProps) {
           </Text>
         </View>
 
-        <TouchableOpacity onPress={handleAdd} activeOpacity={0.7}>
+        <TouchableOpacity onPress={handleAdd} disabled={loading} activeOpacity={0.7}>
           <AddIcon width={47} height={47} />
         </TouchableOpacity>
       </View>
 
       <View style={[styles.footer, { bottom: insets.bottom + 16 }]}>
-        <TouchableOpacity onPress={onFinish} activeOpacity={0.8}>
-          <BtnClicked width={87} height={57} />
+        <TouchableOpacity onPress={onFinish} disabled={loading} activeOpacity={0.8}>
+          <View style={styles.finishWrap}>
+            {loading ? (
+              <LinearGradient
+                colors={['#F69F7B', '#F99CC0']}
+                start={{ x: 0, y: 0 }}
+                end={{ x: 1, y: 0 }}
+                style={[styles.loadingPill, styles.finishDisabled]}
+              >
+                <ActivityIndicator size="small" color="#FFFFFF" />
+              </LinearGradient>
+            ) : (
+              <BtnClicked width={87} height={57} />
+            )}
+          </View>
         </TouchableOpacity>
       </View>
     </View>
@@ -92,4 +111,20 @@ const styles = StyleSheet.create({
     position: 'absolute',
     alignItems: 'center',
   },
+  finishWrap: {
+    width: 87,
+    height: 57,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  finishDisabled: {
+    opacity: 0.7,
+  },
+  loadingPill: {
+    width: 87,
+    height: 57,
+    borderRadius: 28.5,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
 });

client/components/onboarding/SelectionStep.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { View, StyleSheet, TouchableOpacity, ScrollView, Text } from 'react-native';
+import { View, StyleSheet, TouchableOpacity, ScrollView, Text, Platform, useWindowDimensions } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { OnboardingColors, OnboardingFont } from '@/constants/OnboardingTheme';
 import BtnNotClicked from '@/assets/images/icon/btn_Notclicked.svg';
@@ -19,9 +19,12 @@ interface SelectionStepProps {
 }
 
 export function SelectionStep({ options, selectedIds, onToggle, onNext, onSkip }: SelectionStepProps) {
+  const { width, height } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(width, height) >= 768;
+  const maxOptionWidth = isTablet ? 560 : undefined;
   const hasSelection = selectedIds.length > 0;
   const insets = useSafeAreaInsets();
-  const footerBottom = insets.bottom + 16;
+  const footerBottom = insets.bottom + (isTablet ? 38 : 28);
   const footerButtonHeight = 57;
   // 底部留白加大，避免最后一项与按钮边框视觉重叠
   const footerPaddingBottom = footerBottom + footerButtonHeight + 40;
@@ -31,14 +34,24 @@ export function SelectionStep({ options, selectedIds, onToggle, onNext, onSkip }
       <ScrollView
         style={styles.scroll}
         showsVerticalScrollIndicator={false}
-        contentContainerStyle={[styles.optionsList, { paddingBottom: footerPaddingBottom }]}
+        contentContainerStyle={[
+          styles.optionsList,
+          {
+            paddingBottom: footerPaddingBottom,
+            alignItems: 'center',
+          },
+        ]}
       >
         {options.map((option) => {
           const isSelected = selectedIds.includes(option.id);
           return (
             <TouchableOpacity
               key={option.id}
-              style={[styles.optionCard, isSelected && styles.optionCardSelected]}
+              style={[
+                styles.optionCard,
+                maxOptionWidth ? { maxWidth: maxOptionWidth } : null,
+                isSelected && styles.optionCardSelected,
+              ]}
               onPress={() => onToggle(option.id)}
               activeOpacity={0.7}
             >

client/components/ui/SheetModal.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState, useRef } from 'react';
-import { Modal, Pressable, StyleSheet, Text, View, PanResponder, Animated as RNAnimated, Dimensions, Image, ImageSourcePropType } from 'react-native';
+import { Modal, Pressable, StyleSheet, Text, View, PanResponder, Animated as RNAnimated, Image, ImageSourcePropType, Platform, useWindowDimensions } from 'react-native';
 import { useTranslation } from 'react-i18next';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import Animated, {
@@ -10,7 +10,6 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 
-const { height: SCREEN_HEIGHT } = Dimensions.get('window');
 const FIXED_TOP_GAP = 100; // 统一距离顶部的高度
 
 type Props = {
@@ -30,11 +29,13 @@ type Props = {
 export default function SheetModal({ visible, title, onClose, children, leftIcon, height: customHeight }: Props) {
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+  const isTablet = Platform.OS === 'ios' && Math.min(windowWidth, windowHeight) >= 768;
   const [mounted, setMounted] = useState(false);
   const progress = useSharedValue(0); // 0: 关闭, 1: 打开
   const dragY = useSharedValue(0); // 拖拽位移
 
-  const sheetHeight = customHeight || (SCREEN_HEIGHT - FIXED_TOP_GAP);
+  const sheetHeight = customHeight || (isTablet ? Math.min(windowHeight - 72, 760) : (windowHeight - FIXED_TOP_GAP));
 
   useEffect(() => {
     if (visible) {
@@ -90,7 +91,10 @@ export default function SheetModal({ visible, title, onClose, children, leftIcon
     };
   });
 
-  const containerPaddingBottom = useMemo(() => Math.max(insets.bottom, 80), [insets.bottom]); // 增加底部间距至 80，约占 350 高度的 22%，确保内容不被截断并留出足够呼吸感
+  const containerPaddingBottom = useMemo(() => {
+    if (customHeight) return Math.max(insets.bottom, 16);
+    return Math.max(insets.bottom, isTablet ? 20 : 80);
+  }, [customHeight, insets.bottom, isTablet]);
 
   // 注意：Modal 的 visible 必须为 true 才会渲染，因此用 mounted 保持退场动画
   return (
@@ -107,6 +111,7 @@ export default function SheetModal({ visible, title, onClose, children, leftIcon
           {...panResponder.panHandlers}
           style={[
             styles.sheet,
+            isTablet ? styles.sheetTablet : null,
             sheetStyle,
             {
               height: sheetHeight,
@@ -159,6 +164,14 @@ const styles = StyleSheet.create({
     paddingTop: 8,
     paddingHorizontal: 16,
   },
+  sheetTablet: {
+    width: '100%',
+    alignSelf: 'stretch',
+    borderTopLeftRadius: 24,
+    borderTopRightRadius: 24,
+    borderBottomLeftRadius: 0,
+    borderBottomRightRadius: 0,
+  },
   handleContainer: {
     alignItems: 'center',
     paddingVertical: 8,

client/eas.json

@@ -0,0 +1,21 @@
+{
+  "cli": {
+    "version": ">= 16.32.0",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal"
+    },
+    "production": {
+      "autoIncrement": true
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

client/ios/Podfile.lock

@@ -2540,30 +2540,30 @@ EXTERNAL SOURCES:
     :path: "../node_modules/react-native/ReactCommon/yoga"
 
 SPEC CHECKSUMS:
-  EXApplication: 1e98d4b1dccdf30627f92917f4b2c5a53c330e5f
-  EXConstants: fce59a631a06c4151602843667f7cfe35f81e271
+  EXApplication: 13420f8139864183f8a04fd6099077bdf8cfb186
+  EXConstants: 3feb66fd1d94202fc1f0946d74e029d8b224b60e
   EXJSONUtils: 1d3e4590438c3ee593684186007028a14b3686cd
-  EXManifests: a8d97683e5c7a3b026ffbd58559c64dc655b747b
-  EXNotifications: 9eec98712cc814ceff916d876cb53859003b0597
-  Expo: 4e503a041c59c4e34c8be262a135848ad5cd3710
-  expo-dev-client: 425ee077d6754a98cfe3a2e2410d29b440b24c9d
-  expo-dev-launcher: a4f4cdef064ab1fb8621e5b8c7c457cd6e9568c3
-  expo-dev-menu: 05b18812110c175814c6af0d09dd658abcc5e00d
+  EXManifests: 83ef0844fcf06d6099b12a7bdbd7d36fc0e1dd16
+  EXNotifications: 2a3feb7af6194828d9aafda72f63a9a03866230a
+  Expo: b8d64eb9a496ebe8c71e3dae7eeb7f394b146b80
+  expo-dev-client: 12ef7d5b14d93e309922acea78dcd851db583a87
+  expo-dev-launcher: 47994056008ffdc30a6a5e328a375b3e30a8db05
+  expo-dev-menu: ea4fb803ace52e60d7cd8060c7cd379612a140b2
   expo-dev-menu-interface: 600df12ea01efecdd822daaf13cc0ac091775533
-  ExpoAsset: f867e55ceb428aab99e1e8c082b5aee7c159ea18
-  ExpoCrypto: b6105ebaa15d6b38a811e71e43b52cd934945322
-  ExpoDevice: 6327c3c200816795708885adf540d26ecab83d1a
-  ExpoFileSystem: 858a44267a3e6e9057e0888ad7c7cfbf55d52063
-  ExpoFont: f543ce20a228dd702813668b1a07b46f51878d47
-  ExpoHead: 4425246bc93411f0fe7f6945f95f698e91db8780
-  ExpoKeepAwake: 55f75eca6499bb9e4231ebad6f3e9cb8f99c0296
-  ExpoLinearGradient: 809102bdb979f590083af49f7fa4805cd931bd58
-  ExpoLinking: 8f0aaf69aa56f832913030503b6263dc6f647f37
-  ExpoLocalization: d9168d5300a5b03e5e78b986124d11fb6ec3ebbd
-  ExpoModulesCore: f3da4f1ab5a8375d0beafab763739dbee8446583
-  ExpoSplashScreen: bc3cffefca2716e5f22350ca109badd7e50ec14d
-  ExpoWebBrowser: 17b064c621789e41d4816c95c93f429b84971f52
-  EXUpdatesInterface: 5adf50cb41e079c861da6d9b4b954c3db9a50734
+  ExpoAsset: d999f3bbd998a750f3b74cb913229848901b926b
+  ExpoCrypto: 4d23a9ff67c25e2ed23ca792d81e58817a7ea1b9
+  ExpoDevice: 0773c782b055558ca9b40b74aa4a8133a66cd0d2
+  ExpoFileSystem: aefcd337b94b874f88752ebefc52813b84992fad
+  ExpoFont: c625dbd97ed57e9089b172b2a7bb99003d074664
+  ExpoHead: b691a2ed7ab02ed820b6c6468941832d34969c29
+  ExpoKeepAwake: 44bf6715bc1d2ddb17afe19d927cd039cda123f0
+  ExpoLinearGradient: 814a21fc4056c3cf606e4f19e31e47074c5b5a86
+  ExpoLinking: ebf543fd411d56375cb4eee07f6ab4e31c7ad959
+  ExpoLocalization: 6ac6f326210f0a3141ef6f58ab8f8f4ed003b485
+  ExpoModulesCore: 77496909fd3c800f97f7f2007dd26aeac4bb3798
+  ExpoSplashScreen: 72fbc6dd9d6404dd9d0725a56c9ac1383bc0b14f
+  ExpoWebBrowser: 88b116cd378d9609c776c0903fe4070fca461588
+  EXUpdatesInterface: 1436757deb0d574b84bba063bd024c315e0ec08b
   FBLazyVector: e95a291ad2dadb88e42b06e0c5fb8262de53ec12
   hermes-engine: 9f4dfe93326146a1c99eb535b1cb0b857a3cd172
   RCTDeprecation: 943572d4be82d480a48f4884f670135ae30bf990
@@ -2571,72 +2571,72 @@ SPEC CHECKSUMS:
   RCTTypeSafety: 16a4144ca3f959583ab019b57d5633df10b5e97c
   React: 914f8695f9bf38e6418228c2ffb70021e559f92f
   React-callinvoker: 1c0808402aee0c6d4a0d8e7220ce6547af9fba71
-  React-Core: c61410ef0ca6055e204a963992e363227e0fd1c5
-  React-Core-prebuilt: 02f0ad625ddd47463c009c2d0c5dd35c0d982599
-  React-CoreModules: 1f6d1744b5f9f2ec684a4bb5ced25370f87e5382
-  React-cxxreact: 3af79478e8187b63ffc22b794cd42d3fc1f1f2da
+  React-Core: 4ae98f9e8135b8ddbd7c98730afb6fdae883db90
+  React-Core-prebuilt: 8f4cca589c14e8cf8fc6db4587ef1c2056b5c151
+  React-CoreModules: e878a90bb19b8f3851818af997dbae3b3b0a27ac
+  React-cxxreact: 28af9844f6dc87be1385ab521fbfb3746f19563c
   React-debug: 6328c2228e268846161f10082e80dc69eac2e90a
-  React-defaultsnativemodule: d635ef36d755321e5d6fc065bd166b2c5a0e9833
-  React-domnativemodule: dd28f6d96cd21236e020be2eff6fe0b7d4ec3b66
-  React-Fabric: 2e32c3fdbb1fbcf5fde54607e3abe453c6652ce2
-  React-FabricComponents: 5ed0cdb81f6b91656cb4d3be432feaa28a58071a
-  React-FabricImage: 2bc714f818cb24e454f5d3961864373271b2faf8
-  React-featureflags: 847642f41fa71ad4eec5e0351badebcad4fe6171
-  React-featureflagsnativemodule: c868a544b2c626fa337bcbd364b1befe749f0d3f
-  React-graphics: 192ec701def5b3f2a07db2814dfba5a44986cff6
-  React-hermes: e875778b496c86d07ab2ccaa36a9505d248a254b
-  React-idlecallbacksnativemodule: 4d57965cdf82c14ee3b337189836cd8491632b76
-  React-ImageManager: bd0b99e370b13de82c9cd15f0f08144ff3de079e
-  React-jserrorhandler: a2fdef4cbcfdcdf3fa9f5d1f7190f7fd4535248d
-  React-jsi: 89d43d1e7d4d0663f8ba67e0b39eb4e4672c27de
-  React-jsiexecutor: abe4874aaab90dfee5dec480680220b2f8af07e3
-  React-jsinspector: a0b3e051aef842b0b2be2353790ae2b2a5a65a8f
-  React-jsinspectorcdp: 6346013b2247c6263fbf5199adf4a8751e53bd89
-  React-jsinspectornetwork: 26281aa50d49fc1ec93abf981d934698fa95714f
-  React-jsinspectortracing: 55eedf6d57540507570259a778663b90060bbd6e
-  React-jsitooling: 0e001113fa56d8498aa8ac28437ac0d36348e51a
-  React-jsitracing: b713793eb8a5bbc4d86a84e9d9e5023c0f58cbaf
-  React-logger: 50fdb9a8236da90c0b1072da5c32ee03aeb5bf28
-  React-Mapbuffer: 9050ee10c19f4f7fca8963d0211b2854d624973e
-  React-microtasksnativemodule: f775db9e991c6f3b8ccbc02bfcde22770f96e23b
-  react-native-safe-area-context: 37e680fc4cace3c0030ee46e8987d24f5d3bdab2
-  React-NativeModulesApple: 8969913947d5b576de4ed371a939455a8daf28aa
+  React-defaultsnativemodule: afc9d809ec75780f39464a6949c07987fbea488c
+  React-domnativemodule: 91a233260411d41f27f67aa1358b7f9f0bfd101d
+  React-Fabric: 21f349b5e93f305a3c38c885902683a9c79cf983
+  React-FabricComponents: 47ac634cc9ecc64b30a9997192f510eebe4177e4
+  React-FabricImage: 21873acd6d4a51a0b97c133141051c7acb11cc86
+  React-featureflags: 653f469f0c3c9dc271d610373e3b6e66a9fd847d
+  React-featureflagsnativemodule: c91a8a3880e0f4838286402241ead47db43aed28
+  React-graphics: b4bdb0f635b8048c652a5d2b73eb8b1ddd950f24
+  React-hermes: fcfad3b917400f49026f3232561e039c9d1c34bf
+  React-idlecallbacksnativemodule: 8cb83207e39f8179ac1d344b6177c6ab3ccebcdc
+  React-ImageManager: 396128004783fc510e629124dce682d38d1088e7
+  React-jserrorhandler: b58b788d788cdbf8bda7db74a88ebfcffc8a0795
+  React-jsi: d2c3f8555175371c02da6dfe7ed1b64b55a9d6c0
+  React-jsiexecutor: ba537434eb45ee018b590ed7d29ee233fddb8669
+  React-jsinspector: f21b6654baf96cb9f71748844a32468a5f73ad51
+  React-jsinspectorcdp: 3f8be4830694c3c1c39442e50f8db877966d43f0
+  React-jsinspectornetwork: 70e41469565712ad60e11d9c8b8f999b9f7f61eb
+  React-jsinspectortracing: eccf9bfa4ec7f130d514f215cfb2222dc3c0e270
+  React-jsitooling: b376a695f5a507627f7934748533b24eed1751ca
+  React-jsitracing: 5c8c3273dda2d95191cc0612fb5e71c4d9018d2a
+  React-logger: c3e2f8a2e284341205f61eef3d4677ab5a309dfd
+  React-Mapbuffer: 603c18db65844bb81dbe62fee8fcc976eaeb7108
+  React-microtasksnativemodule: d77e0c426fce34c23227394c96ca1033b30c813c
+  react-native-safe-area-context: 53f796cb6c814661bbe99fbdfd0585d07b996cdd
+  React-NativeModulesApple: 1664340b8750d64e0ef3907c5e53d9481f74bcbd
   React-oscompat: ce47230ed20185e91de62d8c6d139ae61763d09c
-  React-perflogger: 02b010e665772c7dcb859d85d44c1bfc5ac7c0e4
-  React-performancetimeline: 130db956b5a83aa4fb41ddf5ae68da89f3fb1526
+  React-perflogger: b1af3cfb3f095f819b2814910000392a8e17ba9f
+  React-performancetimeline: f9ec65b77bcadbc7bd8b47a6f4b4b697da7b1490
   React-RCTActionSheet: 0b14875b3963e9124a5a29a45bd1b22df8803916
-  React-RCTAnimation: a7b90fd2af7bb9c084428867445a1481a8cb112e
-  React-RCTAppDelegate: 3262bedd01263f140ec62b7989f4355f57cec016
-  React-RCTBlob: c17531368702f1ebed5d0ada75a7cf5915072a53
-  React-RCTFabric: 6409edd8cfdc3133b6cc75636d3b858fdb1d11ea
-  React-RCTFBReactNativeSpec: c004b27b4fa3bd85878ad2cf53de3bbec85da797
-  React-RCTImage: c68078a120d0123f4f07a5ac77bea3bb10242f32
-  React-RCTLinking: cf8f9391fe7fe471f96da3a5f0435235eca18c5b
-  React-RCTNetwork: ca31f7c879355760c2d9832a06ee35f517938a20
-  React-RCTRuntime: a6cf4a1e42754fc87f493e538f2ac6b820e45418
-  React-RCTSettings: e0e140b2ff4bf86d34e9637f6316848fc00be035
-  React-RCTText: 75915bace6f7877c03a840cc7b6c622fb62bfa6b
-  React-RCTVibration: 25f26b85e5e432bb3c256f8b384f9269e9529f25
+  React-RCTAnimation: 60f6eca214a62b9673f64db6df3830cee902b5af
+  React-RCTAppDelegate: 37734b39bac108af30a0fd9d3e1149ec68b82c28
+  React-RCTBlob: 83fbcbd57755caf021787324aac2fe9b028cc264
+  React-RCTFabric: a05cb1df484008db3753c8b4a71e4c6d9f1e43a6
+  React-RCTFBReactNativeSpec: d58d7ae9447020bbbac651e3b0674422aba18266
+  React-RCTImage: 47aba3be7c6c64f956b7918ab933769602406aac
+  React-RCTLinking: 2dbaa4df2e4523f68baa07936bd8efdfa34d5f31
+  React-RCTNetwork: 1fca7455f9dedf7de2b95bec438da06680f3b000
+  React-RCTRuntime: 17819dd1dfc8613efaf4cbb9d8686baae4a83e5b
+  React-RCTSettings: 01bf91c856862354d3d2f642ccb82f3697a4284a
+  React-RCTText: cb576a3797dcb64933613c522296a07eaafc0461
+  React-RCTVibration: 560af8c086741f3525b8456a482cdbe27f9d098e
   React-rendererconsistency: 2dac03f448ff337235fd5820b10f81633328870d
-  React-renderercss: 477da167bb96b5ac86d30c5d295412fb853f5453
-  React-rendererdebug: 2a1798c6f3ef5f22d466df24c33653edbabb5b89
-  React-RuntimeApple: 28cf4d8eb18432f6a21abbed7d801ab7f6b6f0b4
-  React-RuntimeCore: 41bf0fd56a00de5660f222415af49879fa49c4f0
-  React-runtimeexecutor: 1afb774dde3011348e8334be69d2f57a359ea43e
-  React-RuntimeHermes: f3b158ea40e8212b1a723a68b4315e7a495c5fc6
-  React-runtimescheduler: 3e1e2bec7300bae512533107d8e54c6e5c63fe0f
-  React-timing: 6fa9883de2e41791e5dc4ec404e5e37f3f50e801
-  React-utils: 6e2035b53d087927768649a11a26c4e092448e34
-  ReactAppDependencyProvider: 1bcd3527ac0390a1c898c114f81ff954be35ed79
-  ReactCodegen: 7d4593f7591f002d137fe40cef3f6c11f13c88cc
-  ReactCommon: 08810150b1206cc44aecf5f6ae19af32f29151a8
+  React-renderercss: c5c6b7a15948dd28facca39a18ac269073718490
+  React-rendererdebug: 3c9d5e1634273f5a24d84cc5669f290ce0bdc812
+  React-RuntimeApple: 887637d1e12ea8262df7d32bc100467df2302613
+  React-RuntimeCore: 91f779835dc4f8f84777fe5dd24f1a22f96454e4
+  React-runtimeexecutor: 8bb6b738f37b0ada4a6269e6f8ab1133dea0285c
+  React-RuntimeHermes: 4cb93de9fa8b1cc753d200dbe61a01b9ec5f5562
+  React-runtimescheduler: 83dc28f530bfbd2fce84ed13aa7feebdc24e5af7
+  React-timing: 03c7217455d2bff459b27a3811be25796b600f47
+  React-utils: 6d46795ae0444ec8a5d9a5f201157b286bf5250a
+  ReactAppDependencyProvider: c277c5b231881ad4f00cd59e3aa0671b99d7ebee
+  ReactCodegen: 4c44b74b77fc41ae25b9e2c7e9bd6e2bc772c23f
+  ReactCommon: e6e232202a447d353e5531f2be82f50f47cbaa9a
   ReactNativeDependencies: 71ce9c28beb282aa720ea7b46980fff9669f428a
-  RNCAsyncStorage: 3a4f5e2777dae1688b781a487923a08569e27fe4
-  RNGestureHandler: e0d0bce5599f6120b7adf90c38d2805e2935795f
-  RNReanimated: e5c702a3e24cc1c68b2de67671713f35461678f4
-  RNScreens: d8d6f1792f6e7ac12b0190d33d8d390efc0c1845
-  RNSVG: 31d6639663c249b7d5abc9728dde2041eb2a3c34
-  RNWorklets: 76fce72926e28e304afb44f0da23b2d24f2c1fa0
+  RNCAsyncStorage: e85a99325df9eb0191a6ee2b2a842644c7eb29f4
+  RNGestureHandler: 40c2d1c168e54715fe52e0fb16cb38c54611e4f3
+  RNReanimated: 43f611f1c85c90e0273df7399bf1536f8e2bd125
+  RNScreens: dd61bc3a3e6f6901ad833efa411917d44827cf51
+  RNSVG: 2825ee146e0f6a16221e852299943e4cceef4528
+  RNWorklets: 28ee7370ca8da356fcc914e3e68b97e9752196d2
   Yoga: 5934998fbeaef7845dbf698f698518695ab4cd1a
 
 PODFILE CHECKSUM: c2c3838f0b2a579fef2350bff2ecaa005e27145d

client/ios/client.xcodeproj/project.pbxproj

@@ -3,7 +3,7 @@
 	archiveVersion = 1;
 	classes = {
 	};
-	objectVersion = 56;
+	objectVersion = 70;
 	objects = {
 
 /* Begin PBXBuildFile section */
@@ -11,12 +11,13 @@
 		13B07FBF1A68108700A75B9A /* Images.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 13B07FB51A68108700A75B9A /* Images.xcassets */; };
 		1A1DE01D4133812B2E2BA692 /* libPods-client.a in Frameworks */ = {isa = PBXBuildFile; fileRef = E3328F0E595C1F4A244DF238 /* libPods-client.a */; };
 		3E461D99554A48A4959DE609 /* SplashScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = AA286B85B6C04FC6940260E9 /* SplashScreen.storyboard */; };
-		A1B2C3D4E5F60718293A4B5C /* EmotionWidget.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1B2C3D4E5F60718293A4B5B /* EmotionWidget.swift */; };
+		A1B2C3D4E5F60718293A4B5C /* 情绪小组件/EmotionWidget.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1B2C3D4E5F60718293A4B5B /* 情绪小组件/EmotionWidget.swift */; };
 		A8C1D2E3F4A5B6C7D8E9F0A2 /* AppGroupStorage.swift in Sources */ = {isa = PBXBuildFile; fileRef = A8C1D2E3F4A5B6C7D8E9F0A1 /* AppGroupStorage.swift */; };
 		A8C1D2E3F4A5B6C7D8E9F0A3 /* WidgetKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = EB3DAF802F2A4B8D00450593 /* WidgetKit.framework */; };
 		A8C1D2E3F4A5B6C7D8E9F0B2 /* AppGroupStorageBridge.m in Sources */ = {isa = PBXBuildFile; fileRef = A8C1D2E3F4A5B6C7D8E9F0B1 /* AppGroupStorageBridge.m */; };
 		B5A7FE9A125F7C79753EC5BF /* ExpoModulesProvider.swift in Sources */ = {isa = PBXBuildFile; fileRef = C7DB40C26E3A46F6D06769EA /* ExpoModulesProvider.swift */; };
 		BB2F792D24A3F905000567C9 /* Expo.plist in Resources */ = {isa = PBXBuildFile; fileRef = BB2F792C24A3F905000567C9 /* Expo.plist */; };
+		C0A1B2C3D4E5F60718293A4E /* Screen_page.png in Resources */ = {isa = PBXBuildFile; fileRef = C0A1B2C3D4E5F60718293A4D /* Screen_page.png */; };
 		EB3DAF812F2A4B8E00450593 /* WidgetKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = EB3DAF802F2A4B8D00450593 /* WidgetKit.framework */; };
 		EB3DAF832F2A4B8E00450593 /* SwiftUI.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = EB3DAF822F2A4B8E00450593 /* SwiftUI.framework */; };
 		EB3DAF942F2A4B8F00450593 /* 情绪小组件Extension.appex in Embed Foundation Extensions */ = {isa = PBXBuildFile; fileRef = EB3DAF7F2F2A4B8D00450593 /* 情绪小组件Extension.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
@@ -48,16 +49,17 @@
 /* End PBXCopyFilesBuildPhase section */
 
 /* Begin PBXFileReference section */
-		13B07F961A680F5B00A75B9A /* HeyMama.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = HeyMama.app; sourceTree = BUILT_PRODUCTS_DIR; };
+		13B07F961A680F5B00A75B9A /* DearMama.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = DearMama.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		13B07FB51A68108700A75B9A /* Images.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; name = Images.xcassets; path = client/Images.xcassets; sourceTree = "<group>"; };
 		13B07FB61A68108700A75B9A /* Info.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; name = Info.plist; path = client/Info.plist; sourceTree = "<group>"; };
 		3C76CA16D0801CBF0D731C7C /* Pods-client.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-client.release.xcconfig"; path = "Target Support Files/Pods-client/Pods-client.release.xcconfig"; sourceTree = "<group>"; };
 		75F52ADE07CAE9D9736D7671 /* PrivacyInfo.xcprivacy */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xml; name = PrivacyInfo.xcprivacy; path = client/PrivacyInfo.xcprivacy; sourceTree = "<group>"; };
-		A1B2C3D4E5F60718293A4B5B /* EmotionWidget.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "情绪小组件/EmotionWidget.swift"; sourceTree = "<group>"; };
+		A1B2C3D4E5F60718293A4B5B /* 情绪小组件/EmotionWidget.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "情绪小组件/EmotionWidget.swift"; sourceTree = "<group>"; };
 		A8C1D2E3F4A5B6C7D8E9F0A1 /* AppGroupStorage.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; name = AppGroupStorage.swift; path = client/AppGroupStorage.swift; sourceTree = "<group>"; };
 		A8C1D2E3F4A5B6C7D8E9F0B1 /* AppGroupStorageBridge.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; name = AppGroupStorageBridge.m; path = client/AppGroupStorageBridge.m; sourceTree = "<group>"; };
 		AA286B85B6C04FC6940260E9 /* SplashScreen.storyboard */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = file.storyboard; name = SplashScreen.storyboard; path = client/SplashScreen.storyboard; sourceTree = "<group>"; };
 		BB2F792C24A3F905000567C9 /* Expo.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; path = Expo.plist; sourceTree = "<group>"; };
+		C0A1B2C3D4E5F60718293A4D /* Screen_page.png */ = {isa = PBXFileReference; lastKnownFileType = image.png; name = Screen_page.png; path = ../assets/images/Screen_page.png; sourceTree = "<group>"; };
 		C7DB40C26E3A46F6D06769EA /* ExpoModulesProvider.swift */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.swift; name = ExpoModulesProvider.swift; path = "Pods/Target Support Files/Pods-client/ExpoModulesProvider.swift"; sourceTree = "<group>"; };
 		E3328F0E595C1F4A244DF238 /* libPods-client.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = "libPods-client.a"; sourceTree = BUILT_PRODUCTS_DIR; };
 		EB3DAF7F2F2A4B8D00450593 /* 情绪小组件Extension.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = "情绪小组件Extension.appex"; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -72,7 +74,7 @@
 /* End PBXFileReference section */
 
 /* Begin PBXFileSystemSynchronizedBuildFileExceptionSet section */
-		EB3DAF952F2A4B8F00450593 /* Exceptions for "情绪小组件" folder in "情绪小组件Extension" target */ = {
+		EB3DAF952F2A4B8F00450593 /* PBXFileSystemSynchronizedBuildFileExceptionSet */ = {
 			isa = PBXFileSystemSynchronizedBuildFileExceptionSet;
 			membershipExceptions = (
 				EmotionWidget.swift,
@@ -83,18 +85,7 @@
 /* End PBXFileSystemSynchronizedBuildFileExceptionSet section */
 
 /* Begin PBXFileSystemSynchronizedRootGroup section */
-		EB3DAF842F2A4B8E00450593 /* 情绪小组件 */ = {
-			isa = PBXFileSystemSynchronizedRootGroup;
-			exceptions = (
-				EB3DAF952F2A4B8F00450593 /* Exceptions for "情绪小组件" folder in "情绪小组件Extension" target */,
-			);
-			explicitFileTypes = {
-			};
-			explicitFolders = (
-			);
-			path = "情绪小组件";
-			sourceTree = "<group>";
-		};
+		EB3DAF842F2A4B8E00450593 /* 情绪小组件 */ = {isa = PBXFileSystemSynchronizedRootGroup; exceptions = (EB3DAF952F2A4B8F00450593 /* PBXFileSystemSynchronizedBuildFileExceptionSet */, ); explicitFileTypes = {}; explicitFolders = (); path = "情绪小组件"; sourceTree = "<group>"; };
 /* End PBXFileSystemSynchronizedRootGroup section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -131,6 +122,7 @@
 				13B07FB51A68108700A75B9A /* Images.xcassets */,
 				13B07FB61A68108700A75B9A /* Info.plist */,
 				AA286B85B6C04FC6940260E9 /* SplashScreen.storyboard */,
+				C0A1B2C3D4E5F60718293A4D /* Screen_page.png */,
 				75F52ADE07CAE9D9736D7671 /* PrivacyInfo.xcprivacy */,
 			);
 			name = client;
@@ -183,7 +175,7 @@
 		83CBBA001A601CBA00E9B192 /* Products */ = {
 			isa = PBXGroup;
 			children = (
-				13B07F961A680F5B00A75B9A /* HeyMama.app */,
+				13B07F961A680F5B00A75B9A /* DearMama.app */,
 				EB3DAF7F2F2A4B8D00450593 /* 情绪小组件Extension.appex */,
 			);
 			name = Products;
@@ -210,7 +202,7 @@
 		EB3DAFD42F2A5FC100450593 /* Recovered References */ = {
 			isa = PBXGroup;
 			children = (
-				A1B2C3D4E5F60718293A4B5B /* EmotionWidget.swift */,
+				A1B2C3D4E5F60718293A4B5B /* 情绪小组件/EmotionWidget.swift */,
 			);
 			name = "Recovered References";
 			sourceTree = "<group>";
@@ -247,7 +239,7 @@
 			);
 			name = client;
 			productName = client;
-			productReference = 13B07F961A680F5B00A75B9A /* HeyMama.app */;
+			productReference = 13B07F961A680F5B00A75B9A /* DearMama.app */;
 			productType = "com.apple.product-type.application";
 		};
 		EB3DAF7E2F2A4B8D00450593 /* 情绪小组件Extension */ = {
@@ -298,6 +290,7 @@
 			knownRegions = (
 				en,
 				Base,
+				"zh-Hant",
 			);
 			mainGroup = 83CBB9F61A601CBA00E9B192;
 			productRefGroup = 83CBBA001A601CBA00E9B192 /* Products */;
@@ -318,6 +311,7 @@
 				BB2F792D24A3F905000567C9 /* Expo.plist in Resources */,
 				13B07FBF1A68108700A75B9A /* Images.xcassets in Resources */,
 				3E461D99554A48A4959DE609 /* SplashScreen.storyboard in Resources */,
+				C0A1B2C3D4E5F60718293A4E /* Screen_page.png in Resources */,
 				0BE245B56A79D95AB0A7B4BA /* PrivacyInfo.xcprivacy in Resources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -477,7 +471,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				A1B2C3D4E5F60718293A4B5C /* EmotionWidget.swift in Sources */,
+				A1B2C3D4E5F60718293A4B5C /* 情绪小组件/EmotionWidget.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -522,7 +516,7 @@
 				);
 				OTHER_SWIFT_FLAGS = "$(inherited) -D EXPO_CONFIGURATION_DEBUG";
 				PRODUCT_BUNDLE_IDENTIFIER = com.damer.mindfulness;
-				PRODUCT_NAME = HeyMama;
+				PRODUCT_NAME = DearMama;
 				SKIP_INSTALL = NO;
 				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
 				SUPPORTS_MACCATALYST = NO;
@@ -531,7 +525,7 @@
 				SWIFT_OBJC_BRIDGING_HEADER = "client/client-Bridging-Header.h";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = 1;
+				TARGETED_DEVICE_FAMILY = "1,2";
 				VERSIONING_SYSTEM = "apple-generic";
 			};
 			name = Debug;
@@ -563,7 +557,7 @@
 				);
 				OTHER_SWIFT_FLAGS = "$(inherited) -D EXPO_CONFIGURATION_RELEASE";
 				PRODUCT_BUNDLE_IDENTIFIER = com.damer.mindfulness;
-				PRODUCT_NAME = HeyMama;
+				PRODUCT_NAME = DearMama;
 				SKIP_INSTALL = NO;
 				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
 				SUPPORTS_MACCATALYST = NO;
@@ -571,7 +565,7 @@
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SWIFT_OBJC_BRIDGING_HEADER = "client/client-Bridging-Header.h";
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = 1;
+				TARGETED_DEVICE_FAMILY = "1,2";
 				VERSIONING_SYSTEM = "apple-generic";
 			};
 			name = Release;
@@ -751,7 +745,7 @@
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = 1;
+				TARGETED_DEVICE_FAMILY = "1,2";
 			};
 			name = Debug;
 		};
@@ -803,7 +797,7 @@
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = 1;
+				TARGETED_DEVICE_FAMILY = "1,2";
 			};
 			name = Release;
 		};

client/ios/client.xcodeproj/xcshareddata/xcschemes/Dear Mama.xcscheme

@@ -15,7 +15,7 @@
             <BuildableReference
                BuildableIdentifier = "primary"
                BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
-               BuildableName = "HeyMama.app"
+               BuildableName = "DearMama.app"
                BlueprintName = "client"
                ReferencedContainer = "container:client.xcodeproj">
             </BuildableReference>
@@ -44,7 +44,7 @@
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
-            BuildableName = "HeyMama.app"
+            BuildableName = "DearMama.app"
             BlueprintName = "client"
             ReferencedContainer = "container:client.xcodeproj">
          </BuildableReference>
@@ -61,7 +61,7 @@
          <BuildableReference
             BuildableIdentifier = "primary"
             BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
-            BuildableName = "HeyMama.app"
+            BuildableName = "DearMama.app"
             BlueprintName = "client"
             ReferencedContainer = "container:client.xcodeproj">
          </BuildableReference>
@@ -72,7 +72,7 @@
    </AnalyzeAction>
    <ArchiveAction
       buildConfiguration = "Release"
-      customArchiveName = "Hey Mama"
+      customArchiveName = "Dear Mama"
       revealArchiveInOrganizer = "YES">
       <PostActions>
          <ExecutionAction
@@ -85,7 +85,7 @@
                   <BuildableReference
                      BuildableIdentifier = "primary"
                      BlueprintIdentifier = "13B07F861A680F5B00A75B9A"
-                     BuildableName = "HeyMama.app"
+                     BuildableName = "DearMama.app"
                      BlueprintName = "client"
                      ReferencedContainer = "container:client.xcodeproj">
                   </BuildableReference>

client/ios/client/Info.plist

@@ -7,7 +7,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
-	<string>Hey Mama</string>
+	<string>Dear Mama</string>
 	<key>CFBundleExecutable</key>
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
@@ -38,8 +38,6 @@
 	<string>12.0</string>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
-	<key>NSLocalNetworkUsageDescription</key>
-	<string>用于连接局域网服务以获取内容与同步数据（仅在需要访问内网地址时使用）。</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoads</key>
@@ -47,6 +45,8 @@
 		<key>NSAllowsLocalNetworking</key>
 		<true/>
 	</dict>
+	<key>NSLocalNetworkUsageDescription</key>
+	<string>用于连接局域网服务以获取内容与同步数据（仅在需要访问内网地址时使用）。</string>
 	<key>NSUserActivityTypes</key>
 	<array>
 		<string>$(PRODUCT_BUNDLE_IDENTIFIER).expo.index_route</string>
@@ -60,6 +60,8 @@
 		<string>arm64</string>
 	</array>
 	<key>UIRequiresFullScreen</key>
+	<true/>
+	<key>UIStatusBarHidden</key>
 	<false/>
 	<key>UIStatusBarStyle</key>
 	<string>UIStatusBarStyleDefault</string>
@@ -72,8 +74,6 @@
 	<array>
 		<string>UIInterfaceOrientationPortrait</string>
 		<string>UIInterfaceOrientationPortraitUpsideDown</string>
-		<string>UIInterfaceOrientationLandscapeLeft</string>
-		<string>UIInterfaceOrientationLandscapeRight</string>
 	</array>
 	<key>UIUserInterfaceStyle</key>
 	<string>Automatic</string>

client/ios/client/SplashScreen.storyboard

@@ -17,7 +17,7 @@
                         <rect key="frame" x="0.0" y="0.0" width="393" height="852"/>
                         <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMaxY="YES"/>
                         <subviews>
-                            <imageView id="EXPO-SplashScreen" userLabel="SplashScreenLegacy" image="SplashScreenLegacy" contentMode="scaleAspectFit" clipsSubviews="true" userInteractionEnabled="false" translatesAutoresizingMaskIntoConstraints="false">
+                            <imageView id="EXPO-SplashScreen" userLabel="Screen_page" image="Screen_page" contentMode="scaleAspectFit" clipsSubviews="true" userInteractionEnabled="false" translatesAutoresizingMaskIntoConstraints="false">
                                 <rect key="frame" x="0" y="0" width="414" height="736"/>
                             </imageView>
                         </subviews>
@@ -37,7 +37,7 @@
         </scene>
     </scenes>
     <resources>
-        <image name="SplashScreenLegacy" width="414" height="736"/>
+        <image name="Screen_page" width="414" height="736"/>
         <systemColor name="systemBackgroundColor">
             <color white="1" alpha="1" colorSpace="custom" customColorSpace="genericGamma22GrayColorSpace"/>
         </systemColor>

client/ios/scripts/fix-xcarchive-header.sh

@@ -42,7 +42,7 @@ if [[ -z "$APP_PLIST" ]]; then
 fi
 
 APP_DIR="$(/usr/bin/dirname "$APP_PLIST")"
-APP_NAME="$(/usr/bin/basename "$APP_DIR")" # 例如 HeyMama.app
+APP_NAME="$(/usr/bin/basename "$APP_DIR")" # 例如 DearMama.app
 APP_REL_PATH="Applications/$APP_NAME"
 
 bundle_id="$(/usr/bin/plutil -extract CFBundleIdentifier raw -o - "$APP_PLIST" 2>/dev/null || true)"

client/ios/情绪小组件/EmotionWidget.swift

@@ -9,7 +9,7 @@ private let keyWidgetConfig = "widget.config.v1"
 private let keyWidgetUserProfile = "widget.userProfile.v1_2"
 private let keyWidgetDailyReco = "widget.dailyReco.v1"
 
-private let fallbackTextTC = "你已经很努力了，今天也值得被温柔对待。"
+private let fallbackTextTC = "你已經很努力了，今天也值得被溫柔對待。"
 private let fallbackTextEN = "You’ve been doing great — you deserve kindness today."
 
 private func defaults() -> UserDefaults? {
@@ -29,17 +29,24 @@ private func localDayKey(_ date: Date = Date()) -> String {
 }
 
 private func resolveLang() -> String {
-    // 仅支持 en/tc
-    let preferred = Locale.preferredLanguages.first?.lowercased() ?? "en"
-    return preferred.hasPrefix("zh") ? "tc" : "en"
+    // 仅支持 en/tc：根据设备语言选择
+    // - 传统中文（Hant / TW / HK / MO）=> tc
+    // - 其他语言（含简中 zh-Hans / zh-CN）=> en（默认）
+    let preferred = (Locale.preferredLanguages.first ?? "en").lowercased()
+    if preferred.hasPrefix("zh-hant") { return "tc" }
+    if preferred.hasPrefix("zh-tw") { return "tc" }
+    if preferred.hasPrefix("zh-hk") { return "tc" }
+    if preferred.hasPrefix("zh-mo") { return "tc" }
+    return "en"
 }
 
 private func resolveTitle(lang: String) -> String {
-    lang == "en" ? "Mindfulness" : "正念"
+    // 需求：品牌文案统一为 Dear Mama
+    return "Dear Mama"
 }
 
 private func resolveFooterHint(lang: String) -> String {
-    lang == "en" ? "Tap to open the app" : "点我回到 App"
+    lang == "en" ? "Tap to open the app" : "點我回到 App"
 }
 
 private func joinUrl(base: String, path: String) -> String {
@@ -76,16 +83,44 @@ private func writeJsonDict(_ dict: [String: Any], forKey key: String) {
     defaults()?.set(raw, forKey: key)
 }
 
-private func readCachedText() -> (dayKey: String?, lang: String, text: String)? {
+private func readCachedText(family: WidgetFamily) -> (dayKey: String?, lang: String, text: String)? {
     guard let d = readJsonDict(forKey: keyWidgetDailyReco) else { return nil }
     let lang = (d["lang"] as? String) ?? resolveLang()
     let dayKey = d["day_key"] as? String
-    if let item = d["item"] as? [String: Any], let text = item["text"] as? String, !text.isEmpty {
-        return (dayKey: dayKey, lang: lang, text: text)
+    if let item = d["item"] as? [String: Any] {
+        if let text = pickWidgetText(item: item, family: family), !text.isEmpty {
+            return (dayKey: dayKey, lang: lang, text: text)
+        }
     }
     return nil
 }
 
+private func familyKey(_ family: WidgetFamily) -> String {
+    switch family {
+    case .systemSmall:
+        return "small"
+    case .systemMedium:
+        return "medium"
+    case .systemLarge:
+        return "large"
+    default:
+        return "small"
+    }
+}
+
+private func pickWidgetText(item: [String: Any], family: WidgetFamily?) -> String? {
+    // 优先使用 App 侧预换行的结果（wrapped_text_by_family），否则回退 raw text
+    if let family = family,
+       let wrappedByFamily = item["wrapped_text_by_family"] as? [String: Any] {
+        let key = familyKey(family)
+        if let v = wrappedByFamily[key] as? String, !v.isEmpty {
+            return v
+        }
+    }
+    if let raw = item["text"] as? String, !raw.isEmpty { return raw }
+    return nil
+}
+
 private func readApiBaseUrl() -> String? {
     guard let d = readJsonDict(forKey: keyWidgetConfig) else { return nil }
     let base = d["apiBaseUrl"] as? String
@@ -174,7 +209,7 @@ struct EmotionProvider: TimelineProvider {
             let today = localDayKey(Date())
 
             // 1) 今日缓存优先
-            if let cached = readCachedText(), cached.dayKey == today {
+            if let cached = readCachedText(family: context.family), cached.dayKey == today {
                 let entry = EmotionEntry(
                     date: Date(),
                     lang: cached.lang,
@@ -201,7 +236,7 @@ struct EmotionProvider: TimelineProvider {
             }
 
             // 3) 网络失败：用最近缓存或兜底
-            if let cached = readCachedText() {
+            if let cached = readCachedText(family: context.family) {
                 let entry = EmotionEntry(
                     date: Date(),
                     lang: cached.lang,
@@ -245,12 +280,12 @@ struct EmotionWidgetView: View {
         Text(entry.text)
             .font(fontForFamily())
             .foregroundColor(widgetTextColor)
-            .multilineTextAlignment(.leading)
+            .multilineTextAlignment(.center)
             .lineSpacing(lineSpacingForFamily())
             .lineLimit(lineLimitForFamily())
             .minimumScaleFactor(0.78)
             .padding(paddingForFamily())
-            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .leading)
+            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .center)
             .widgetSolidBackground(widgetBackgroundColor)
             .widgetURL(deepLink)
     }
@@ -332,8 +367,9 @@ struct EmotionWidget: Widget {
         StaticConfiguration(kind: kind, provider: EmotionProvider()) { entry in
             EmotionWidgetView(entry: entry)
         }
-        .configurationDisplayName("情绪小组件")
-        .description("一段温柔提醒，陪你回到当下。")
+        // 名称/描述：支持多语言（使用 Widget Extension 自己的 Localizable.strings）
+        .configurationDisplayName("WIDGET_DISPLAY_NAME")
+        .description("WIDGET_DESCRIPTION")
         .supportedFamilies([.systemSmall, .systemMedium, .systemLarge])
     }
 }

client/ios/情绪小组件/en.lproj/Localizable.strings

@@ -0,0 +1,3 @@
+"WIDGET_DISPLAY_NAME" = "Emotion Widget";
+"WIDGET_DESCRIPTION" = "A gentle reminder to return to the present.";
+

client/ios/情绪小组件/zh-Hant.lproj/Localizable.strings

@@ -0,0 +1,3 @@
+"WIDGET_DISPLAY_NAME" = "情緒小組件";
+"WIDGET_DESCRIPTION" = "一段溫柔提醒，陪你回到當下。";
+

client/metro.config.js

@@ -1,5 +1,6 @@
 // Metro 配置：支持 import 本地 .svg 为 React 组件
 // 说明：Expo SDK 54 + react-native-svg-transformer 的常见配置方式
+const path = require('path');
 const { getDefaultConfig } = require('expo/metro-config');
 
 /** @type {import('expo/metro-config').MetroConfig} */
@@ -14,6 +15,10 @@ config.resolver = {
   ...config.resolver,
   assetExts: config.resolver.assetExts.filter((ext) => ext !== 'svg'),
   sourceExts: [...config.resolver.sourceExts, 'svg'],
+  // 确保 react-native-text-size 从项目 node_modules 解析（避免 Metro 解析不到）
+  extraNodeModules: {
+    'react-native-text-size': path.resolve(__dirname, 'node_modules/react-native-text-size'),
+  },
 };
 
 module.exports = config;

client/package-lock.json

@@ -25,6 +25,7 @@
         "expo-splash-screen": "~31.0.13",
         "expo-status-bar": "~3.0.9",
         "expo-web-browser": "~15.0.10",
+        "grapheme-splitter": "^1.0.4",
         "i18next": "^25.8.0",
         "react": "19.1.0",
         "react-dom": "19.1.0",
@@ -36,6 +37,7 @@
         "react-native-screens": "~4.16.0",
         "react-native-svg": "15.12.1",
         "react-native-svg-transformer": "^1.5.3",
+        "react-native-text-size": "^4.0.0-rc.1",
         "react-native-web": "~0.21.0",
         "react-native-worklets": "0.5.1"
       },
@@ -6958,6 +6960,11 @@
       "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
       "license": "ISC"
     },
+    "node_modules/grapheme-splitter": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmmirror.com/grapheme-splitter/-/grapheme-splitter-1.0.4.tgz",
+      "integrity": "sha512-bzh50DW9kTPM00T8y4o8vQg89Di9oLJVLW/KaOGIXJWP/iqCN6WKYkbNOF04vFLJhwcpYUh9ydh/+5vpOqV4YQ=="
+    },
     "node_modules/has-flag": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
@@ -9708,6 +9715,15 @@
         "react-native-svg": ">=12.0.0"
       }
     },
+    "node_modules/react-native-text-size": {
+      "version": "4.0.0-rc.1",
+      "resolved": "https://registry.npmmirror.com/react-native-text-size/-/react-native-text-size-4.0.0-rc.1.tgz",
+      "integrity": "sha512-CysqjU2jK6Yc+a+kEI222pUyTY2ywcU2HqbFqf1KHymW6OPTdvBBHqbEJKL0QiLhQaFYDbqicM+h990s9TP00g==",
+      "license": "BSD-2-Clause",
+      "peerDependencies": {
+        "react-native": ">=0.59.0"
+      }
+    },
     "node_modules/react-native-web": {
       "version": "0.21.2",
       "resolved": "https://registry.npmjs.org/react-native-web/-/react-native-web-0.21.2.tgz",

client/package.json

@@ -6,8 +6,8 @@
     "start": "expo start",
     "start:clean": "expo start -c",
     "android": "expo run:android",
-    "ios": "expo run:ios --scheme \"Hey Mama\"",
-    "ios:clean": "npm run clean:cache && npm run clean:ios-build && expo run:ios --scheme \"Hey Mama\"",
+    "ios": "expo run:ios --scheme \"Dear Mama\"",
+    "ios:clean": "npm run clean:cache && npm run clean:ios-build && expo run:ios --scheme \"Dear Mama\"",
     "web": "expo start --web",
     "test": "vitest run",
     "clean:cache": "rm -rf node_modules/.cache .expo 2>/dev/null; echo 'Cleared .expo and node_modules/.cache'",
@@ -31,6 +31,7 @@
     "expo-splash-screen": "~31.0.13",
     "expo-status-bar": "~3.0.9",
     "expo-web-browser": "~15.0.10",
+    "grapheme-splitter": "^1.0.4",
     "i18next": "^25.8.0",
     "react": "19.1.0",
     "react-dom": "19.1.0",
@@ -42,6 +43,7 @@
     "react-native-screens": "~4.16.0",
     "react-native-svg": "15.12.1",
     "react-native-svg-transformer": "^1.5.3",
+    "react-native-text-size": "^4.0.0-rc.1",
     "react-native-web": "~0.21.0",
     "react-native-worklets": "0.5.1"
   },

client/src/constants/env.ts

@@ -27,7 +27,7 @@ export type AppRuntimeEnv = 'local' | 'dev' | 'prod';
  * 默认回退到 prod（避免误打到 localhost 导致真机“无法发起网络请求”）。
  */
 const DEFAULT_RUNTIME_ENV: AppRuntimeEnv =
-  typeof __DEV__ !== 'undefined' && __DEV__ ? 'local' : 'prod';
+  typeof __DEV__ !== 'undefined' && __DEV__ ? 'local' : 'dev';
 
 export const APP_ENV = (getOptionalEnv('EXPO_PUBLIC_ENV', DEFAULT_RUNTIME_ENV) as AppRuntimeEnv) ?? DEFAULT_RUNTIME_ENV;
 

client/src/features/textWrap/__tests__/wrapText.integration.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { wrapText } from '../index';
+
+describe('textWrap integration wrapText', () => {
+  it('SYSTEM_DEFAULT：meta 标记 SYSTEM_DEFAULT 且仍返回 lines/wrappedText', async () => {
+    const res = await wrapText({
+      text: 'I am so tired',
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 1,
+      maxLines: 1,
+      overflowMode: 'SYSTEM_DEFAULT',
+      // 不提供测量能力，逼迫走兜底
+      fontSpec: null,
+      measureWidthImpl: undefined,
+    });
+
+    expect(res.lines.length).toBeGreaterThan(0);
+    expect(res.wrappedText.length).toBeGreaterThan(0);
+    expect(res.meta?.fallback_type).toBe('SYSTEM_DEFAULT');
+  });
+});
+

client/src/features/textWrap/breakpoints/__tests__/generateBreakpoints.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import { generateBreakpoints } from '../index';
+
+function t(text: string, start: number): { text: string; start: number; end: number } {
+  return { text, start, end: start + text.length };
+}
+
+describe('textWrap breakpoint-candidates', () => {
+  it('EN: tokens=[I,am,so,tired] -> pos=[1,2,3]（升序）', () => {
+    const tokens = [t('I', 0), t('am', 2), t('so', 5), t('tired', 8)];
+    const { breakpoints, meta } = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'EN',
+      maxLines: 2,
+      config: { tcMaxCandidateBreaks: 80, tcPunctuations: ['，', '。'], balanceRange: 3 },
+    });
+
+    expect(breakpoints.map((b) => b.pos)).toEqual([1, 2, 3]);
+    expect(meta.originalCount).toBe(3);
+    expect(meta.finalCount).toBe(3);
+  });
+
+  it('TC: 标点后断点（，）应生成 pos=i+1', () => {
+    const tokens = [t('我', 0), t('好', 1), t('累', 2), t('，', 3), t('😮‍💨', 4)];
+    const { breakpoints } = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'TC',
+      maxLines: 2,
+      config: { tcMaxCandidateBreaks: 80, tcPunctuations: ['，'], balanceRange: 0 },
+    });
+
+    expect(breakpoints.some((b) => b.kind === 'PUNCT' && b.pos === 4)).toBe(true);
+  });
+
+  it('TC: forbiddenBreakRanges（闭区间）命中必须剔除（含 start/end）', () => {
+    const tokens = [t('我', 0), t('好', 1), t('累', 2), t('，', 3), t('😮‍💨', 4)];
+    const { breakpoints } = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'TC',
+      maxLines: 2,
+      constraints: { forbiddenBreakRanges: [{ start: 4, end: 4 }] },
+      config: { tcMaxCandidateBreaks: 80, tcPunctuations: ['，'], balanceRange: 0 },
+    });
+
+    expect(breakpoints.some((b) => b.pos === 4)).toBe(false);
+  });
+
+  it('TC: 去重规则：同 pos 优先保留 priority 更高者；同 priority 按 kind 序', () => {
+    // 构造：同一个 pos=2 同时来自 SPACE(priority=20) 和 BALANCE(priority=5)，必须保留 SPACE
+    const tokens = [t('我', 0), t(' ', 1), t('好', 2)];
+    const { breakpoints } = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'TC',
+      maxLines: 2,
+      config: { tcMaxCandidateBreaks: 80, tcPunctuations: [], balanceRange: 2 },
+    });
+
+    const b2 = breakpoints.find((b) => b.pos === 2);
+    expect(b2?.kind).toBe('SPACE');
+    expect(b2?.priority).toBe(20);
+  });
+
+  it('TC: 裁剪上限生效且输出按 pos 升序（确定性）', () => {
+    const tokens = Array.from({ length: 60 }).map((_, i) => t('哈', i));
+    const res = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'TC',
+      maxLines: 3,
+      config: { tcMaxCandidateBreaks: 8, tcPunctuations: [], balanceRange: 6 },
+    });
+
+    expect(res.breakpoints.length).toBe(8);
+    // pos 升序
+    for (let i = 1; i < res.breakpoints.length; i++) {
+      expect(res.breakpoints[i]!.pos).toBeGreaterThanOrEqual(res.breakpoints[i - 1]!.pos);
+    }
+    // 确定性
+    const res2 = generateBreakpoints({
+      tokens: tokens as any,
+      lang: 'TC',
+      maxLines: 3,
+      config: { tcMaxCandidateBreaks: 8, tcPunctuations: [], balanceRange: 6 },
+    });
+    expect(res).toEqual(res2);
+  });
+
+  it('边界：N<=1 时不输出任何候选断点', () => {
+    const { breakpoints } = generateBreakpoints({
+      tokens: [t('我', 0)] as any,
+      lang: 'TC',
+      maxLines: 2,
+      config: { tcMaxCandidateBreaks: 80, tcPunctuations: ['，'], balanceRange: 3 },
+    });
+    expect(breakpoints).toEqual([]);
+  });
+});
+

client/src/features/textWrap/breakpoints/enCandidates.ts

@@ -0,0 +1,22 @@
+import type { Breakpoint } from './types';
+import type { Token } from '../core/types';
+
+/**
+ * EN 候选断点生成（极简派）
+ *
+ * 口径：
+ * - tokens 仅为 WORD（不包含 SPACE token）
+ * - 候选断点只生成在 `pos ∈ [1, N-1]`
+ * - kind 固定为 SPACE，priority 固定为 10
+ */
+export function generateEnCandidates(tokens: Token[]): Breakpoint[] {
+  const n = tokens.length;
+  if (n <= 1) return [];
+
+  const out: Breakpoint[] = [];
+  for (let pos = 1; pos <= n - 1; pos++) {
+    out.push({ pos, kind: 'SPACE', priority: 10 });
+  }
+  return out;
+}
+

client/src/features/textWrap/breakpoints/filterAndDedup.ts

@@ -0,0 +1,89 @@
+import type { Breakpoint, BreakpointKind, BreakpointMeta, BreakpointConstraints } from './types';
+
+const KIND_ORDER: Record<BreakpointKind, number> = {
+  PUNCT: 0,
+  SPACE: 1,
+  BALANCE: 2,
+  OTHER: 3,
+};
+
+function betterBreakpoint(a: Breakpoint, b: Breakpoint): Breakpoint {
+  if (a.priority !== b.priority) return a.priority > b.priority ? a : b;
+  const ka = KIND_ORDER[a.kind] ?? 999;
+  const kb = KIND_ORDER[b.kind] ?? 999;
+  if (ka !== kb) return ka < kb ? a : b;
+  // 完全相同优先级时，稳定选择 pos 更小者（但同 pos 才会进入该比较）
+  return a;
+}
+
+/**
+ * forbiddenBreakRanges 过滤（闭区间口径）
+ * - start <= pos && pos <= end 命中则剔除
+ */
+export function filterForbiddenBreakRanges(
+  breakpoints: Breakpoint[],
+  constraints: BreakpointConstraints | undefined
+): Breakpoint[] {
+  const ranges = constraints?.forbiddenBreakRanges;
+  if (!ranges || ranges.length === 0) return breakpoints;
+
+  return breakpoints.filter((bp) => {
+    for (const r of ranges) {
+      const s = r.start | 0;
+      const e = r.end | 0;
+      if (s <= bp.pos && bp.pos <= e) return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * 去重：同 pos 只保留一个 breakpoint（priority 更高者优先；同 priority 按 kind 固定序）
+ */
+export function dedupByPos(breakpoints: Breakpoint[]): Breakpoint[] {
+  const map = new Map<number, Breakpoint>();
+  for (const bp of breakpoints) {
+    const prev = map.get(bp.pos);
+    if (!prev) {
+      map.set(bp.pos, bp);
+      continue;
+    }
+    map.set(bp.pos, betterBreakpoint(prev, bp));
+  }
+  return Array.from(map.values());
+}
+
+export function distanceToNearestIdeal(pos: number, ideals: number[] | undefined): number {
+  if (!ideals || ideals.length === 0) return 1_000_000_000;
+  let best = 1_000_000_000;
+  for (const p of ideals) {
+    const d = Math.abs(pos - p);
+    if (d < best) best = d;
+  }
+  return best;
+}
+
+/**
+ * TC 裁剪（确定性排序后截断）
+ * - priority desc
+ * - distToIdeal asc
+ * - pos asc
+ */
+export function pruneTcCandidates(breakpoints: Breakpoint[], ideals: number[], tcMaxCandidateBreaks: number): Breakpoint[] {
+  if (breakpoints.length <= tcMaxCandidateBreaks) return breakpoints;
+
+  const sorted = [...breakpoints].sort((a, b) => {
+    if (a.priority !== b.priority) return b.priority - a.priority;
+    const da = distanceToNearestIdeal(a.pos, ideals);
+    const db = distanceToNearestIdeal(b.pos, ideals);
+    if (da !== db) return da - db;
+    return a.pos - b.pos;
+  });
+
+  return sorted.slice(0, tcMaxCandidateBreaks);
+}
+
+export function buildMeta(originalCount: number, finalCount: number): BreakpointMeta {
+  return { originalCount, finalCount, pruned: finalCount < originalCount };
+}
+

client/src/features/textWrap/breakpoints/generateBreakpoints.ts

@@ -0,0 +1,59 @@
+import type { Breakpoint, BreakpointMeta, GenerateBreakpointsInput } from './types';
+import { generateEnCandidates } from './enCandidates';
+import { generateTcCandidates } from './tcCandidates';
+import { buildMeta, dedupByPos, filterForbiddenBreakRanges, pruneTcCandidates } from './filterAndDedup';
+
+/**
+ * 生成候选断点（确定性）
+ *
+ * 统一口径：
+ * - 只输出 `pos ∈ [1, N-1]`
+ * - forbiddenBreakRanges 使用闭区间过滤：start <= pos && pos <= end
+ * - 去重按 priority 优先；priority 相同按 kind 固定序：PUNCT > SPACE > BALANCE > OTHER
+ * - TC 超过上限时按固定排序裁剪，然后最终按 pos 升序输出
+ */
+export function generateBreakpoints(input: GenerateBreakpointsInput): { breakpoints: Breakpoint[]; meta: BreakpointMeta } {
+  const tokens = input.tokens ?? [];
+  const n = tokens.length;
+  const lang = input.lang;
+
+  if (n <= 1) {
+    return { breakpoints: [], meta: buildMeta(0, 0) };
+  }
+
+  let raw: Breakpoint[] = [];
+  let ideals: number[] = [];
+
+  if (lang === 'EN') {
+    raw = generateEnCandidates(tokens);
+  } else {
+    const out = generateTcCandidates(tokens, input.maxLines, {
+      tcPunctuations: input.config.tcPunctuations,
+      balanceRange: input.config.balanceRange,
+    });
+    raw = out.candidates;
+    ideals = out.idealPositions;
+  }
+
+  const originalCount = raw.length;
+
+  // 过滤 forbiddenBreakRanges（闭区间）
+  let filtered = filterForbiddenBreakRanges(raw, input.constraints);
+
+  // 去重（同 pos 保留最佳）
+  filtered = dedupByPos(filtered);
+
+  // TC 裁剪（规模上限）
+  if (lang === 'TC') {
+    const max = Math.max(0, input.config.tcMaxCandidateBreaks | 0);
+    if (max > 0) {
+      filtered = pruneTcCandidates(filtered, ideals, max);
+    }
+  }
+
+  // 最终按 pos 升序输出
+  filtered.sort((a, b) => a.pos - b.pos);
+
+  return { breakpoints: filtered, meta: buildMeta(originalCount, filtered.length) };
+}
+

client/src/features/textWrap/breakpoints/index.ts

@@ -0,0 +1,11 @@
+export type {
+  Breakpoint,
+  BreakpointConfig,
+  BreakpointConstraints,
+  BreakpointKind,
+  BreakpointMeta,
+  GenerateBreakpointsInput,
+} from './types';
+
+export { generateBreakpoints } from './generateBreakpoints';
+

client/src/features/textWrap/breakpoints/tcCandidates.ts

@@ -0,0 +1,78 @@
+import type { Breakpoint } from './types';
+import type { Token } from '../core/types';
+
+type TcCandidateConfig = {
+  tcPunctuations: string[];
+  balanceRange: number;
+};
+
+/**
+ * 计算 BALANCE 的 idealPos 列表（确定性简化版）。
+ *
+ * - N=tokens.length
+ * - targetLines=min(maxLines,N)
+ * - lineIndex in 1..targetLines-1：
+ *   idealPos=round(N*lineIndex/targetLines)
+ */
+export function computeTcIdealPositions(tokens: Token[], maxLines: number): number[] {
+  const n = tokens.length;
+  const targetLines = Math.max(1, Math.min(maxLines | 0, n));
+  const ideals: number[] = [];
+
+  for (let lineIndex = 1; lineIndex <= targetLines - 1; lineIndex++) {
+    const idealPos = Math.round((n * lineIndex) / targetLines);
+    ideals.push(idealPos);
+  }
+
+  // 去重并排序（稳定）
+  ideals.sort((a, b) => a - b);
+  return ideals.filter((v, idx) => idx === 0 || v !== ideals[idx - 1]);
+}
+
+/**
+ * TC 候选断点生成：
+ * - 标点后：kind=PUNCT，priority=30
+ * - 空格后：kind=SPACE，priority=20
+ * - BALANCE：kind=BALANCE，priority=5（围绕 idealPos ± balanceRange）
+ *
+ * 注意：BALANCE 断点允许生成在短语 span 内，是否可用交给评分阶段强惩罚淘汰。
+ */
+export function generateTcCandidates(tokens: Token[], maxLines: number, config: TcCandidateConfig): { candidates: Breakpoint[]; idealPositions: number[] } {
+  const n = tokens.length;
+  if (n <= 1) return { candidates: [], idealPositions: [] };
+
+  const punctSet = new Set(config.tcPunctuations);
+  const candidates: Breakpoint[] = [];
+
+  // PUNCT / SPACE（扫描 token）
+  for (let i = 0; i < n; i++) {
+    const t = tokens[i]?.text ?? '';
+    const pos = i + 1;
+
+    // 只允许行内断点
+    if (pos < 1 || pos > n - 1) continue;
+
+    if (punctSet.has(t)) {
+      candidates.push({ pos, kind: 'PUNCT', priority: 30 });
+    }
+
+    if (t === ' ') {
+      candidates.push({ pos, kind: 'SPACE', priority: 20 });
+    }
+  }
+
+  // BALANCE
+  const idealPositions = computeTcIdealPositions(tokens, maxLines);
+  const range = Math.max(0, config.balanceRange | 0);
+  if (range > 0 && idealPositions.length > 0) {
+    for (const ideal of idealPositions) {
+      for (let pos = ideal - range; pos <= ideal + range; pos++) {
+        if (pos < 1 || pos > n - 1) continue;
+        candidates.push({ pos, kind: 'BALANCE', priority: 5 });
+      }
+    }
+  }
+
+  return { candidates, idealPositions };
+}
+

client/src/features/textWrap/breakpoints/types.ts

@@ -0,0 +1,37 @@
+import type { Token } from '../core/types';
+
+export type BreakpointKind = 'PUNCT' | 'SPACE' | 'BALANCE' | 'OTHER';
+
+export type Breakpoint = {
+  /** 断点位置（token 边界）：切分为 [0..pos) + [pos..N) */
+  pos: number;
+  kind: BreakpointKind;
+  /** 候选优先级（用于去重/裁剪阶段），越大越优先 */
+  priority: number;
+};
+
+export type BreakpointMeta = {
+  pruned: boolean;
+  originalCount: number;
+  finalCount: number;
+};
+
+export type BreakpointConstraints = {
+  protectedPhrases?: string[];
+  forbiddenBreakRanges?: Array<{ start: number; end: number }>;
+};
+
+export type BreakpointConfig = {
+  tcMaxCandidateBreaks: number;
+  tcPunctuations: string[];
+  balanceRange: number;
+};
+
+export type GenerateBreakpointsInput = {
+  tokens: Token[];
+  lang: 'TC' | 'EN';
+  maxLines: number;
+  constraints?: BreakpointConstraints;
+  config: BreakpointConfig;
+};
+

client/src/features/textWrap/core/__tests__/core-contract.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  DEFAULT_PUNCTUATION_STRIP_SET_EN,
+  compareBreaksLexicographically,
+  joinTokens,
+  matchENKeyword,
+  normalizeENKeyword,
+  normalizeWhitespace,
+  tokenizeEN,
+} from '../index';
+
+describe('textWrap core-contract', () => {
+  it('normalizeWhitespace(NORMALIZE): 折叠空白 + 去首尾', () => {
+    const out = normalizeWhitespace('  a   b \n c  ', 'NORMALIZE');
+    expect(out.normalizedText).toBe('a b c');
+    expect(out.hadMultiWhitespace).toBe(true);
+  });
+
+  it('tokenizeEN: 只按空白分词（极简派，不拆标点）', () => {
+    const { normalizedText } = normalizeWhitespace('I am so tired.', 'NORMALIZE');
+    const tokens = tokenizeEN(normalizedText);
+    expect(tokens.map((t) => t.text)).toEqual(['I', 'am', 'so', 'tired.']);
+  });
+
+  it('joinTokens: 默认用单空格重组', () => {
+    const { normalizedText } = normalizeWhitespace('I am so tired', 'NORMALIZE');
+    const tokens = tokenizeEN(normalizedText);
+    expect(joinTokens(tokens, 0, 2)).toBe('I am');
+    expect(joinTokens(tokens, 2, 4)).toBe('so tired');
+  });
+
+  it('normalizeENKeyword/matchENKeyword: 全词等值匹配，不做 substring', () => {
+    const config = { punctuationStripSetEN: DEFAULT_PUNCTUATION_STRIP_SET_EN };
+
+    expect(normalizeENKeyword('BUT,', config)).toBe('but');
+    expect(matchENKeyword('but,', 'but', config)).toBe(true);
+    expect(matchENKeyword('rebuttal', 'but', config)).toBe(false);
+  });
+
+  it('compareBreaksLexicographically: 字典序 + 短数组优先', () => {
+    expect(compareBreaksLexicographically([2], [3])).toBeLessThan(0);
+    expect(compareBreaksLexicographically([2], [2, 5])).toBeLessThan(0);
+    expect(compareBreaksLexicographically([2, 3], [2])).toBeGreaterThan(0);
+    expect(compareBreaksLexicographically([2, 3], [2, 3])).toBe(0);
+  });
+});
+

client/src/features/textWrap/core/compare.ts

@@ -0,0 +1,25 @@
+/**
+ * breaks[] 字典序比较（确定性口径）
+ *
+ * 规则（必须）：
+ * - 从 index=0 起逐项比较：
+ *   - 首个不同元素更小者视为更小
+ * - 若公共前缀完全相同：
+ *   - 更短的数组视为更小
+ */
+export function compareBreaksLexicographically(a: number[], b: number[]): number {
+  const aa = Array.isArray(a) ? a : [];
+  const bb = Array.isArray(b) ? b : [];
+
+  const n = Math.min(aa.length, bb.length);
+  for (let i = 0; i < n; i++) {
+    const x = aa[i]!;
+    const y = bb[i]!;
+    if (x === y) continue;
+    return x < y ? -1 : 1;
+  }
+
+  if (aa.length === bb.length) return 0;
+  return aa.length < bb.length ? -1 : 1;
+}
+

client/src/features/textWrap/core/enKeyword.ts

@@ -0,0 +1,68 @@
+import type { CoreConfig } from './types';
+
+/**
+ * EN 常见标点（默认集合）
+ *
+ * 说明：此集合只用于“关键词命中判定”的两端 strip，不影响 tokenize（仍为极简派）。
+ * 必须全端一致；后续若扩展，也必须通过 configVersion 管理。
+ */
+export const DEFAULT_PUNCTUATION_STRIP_SET_EN: string[] = [
+  ',',
+  '.',
+  '!',
+  '?',
+  ':',
+  ';',
+  '"',
+  "'",
+  '…',
+  '—',
+  '–',
+  '(',
+  ')',
+  '[',
+  ']',
+  '{',
+  '}',
+];
+
+function buildStripSet(config?: Pick<CoreConfig, 'punctuationStripSetEN'>): Set<string> {
+  const list = config?.punctuationStripSetEN?.length ? config.punctuationStripSetEN : DEFAULT_PUNCTUATION_STRIP_SET_EN;
+  return new Set(list);
+}
+
+/**
+ * 归一化一个 token，用于 EN 关键词命中（全词等值匹配）。
+ *
+ * 口径（必须）：
+ * - lowercase
+ * - strip 两端常见标点（可重复剥离，例如 `"\"but,\""`）
+ * - 不允许 substring/contains
+ */
+export function normalizeENKeyword(tokenText: string, config?: Pick<CoreConfig, 'punctuationStripSetEN'>): string {
+  const stripSet = buildStripSet(config);
+
+  let s = String(tokenText ?? '').toLowerCase();
+  if (!s) return '';
+
+  // 仅剥离两端的“常见标点”，内部字符不处理
+  let start = 0;
+  let end = s.length;
+
+  while (start < end && stripSet.has(s[start]!)) start++;
+  while (end > start && stripSet.has(s[end - 1]!)) end--;
+
+  // 如果剥离后还剩空白，再做一次 trim（避免 `"but "` 这种输入）
+  return s.slice(start, end).trim();
+}
+
+/**
+ * EN 关键词命中：全词等值匹配（禁止 substring）。
+ */
+export function matchENKeyword(tokenText: string, keyword: string, config?: Pick<CoreConfig, 'punctuationStripSetEN'>): boolean {
+  const a = normalizeENKeyword(tokenText, config);
+  const b = normalizeENKeyword(keyword, config);
+  if (!a || !b) return false;
+  return a === b;
+}
+

client/src/features/textWrap/core/index.ts

@@ -0,0 +1,8 @@
+export type { CoreConfig, Lang, NormalizeWhitespaceResult, Token, WhitespacePolicy } from './types';
+
+export { normalizeWhitespace } from './normalizeWhitespace';
+export { tokenizeEN } from './tokenizeEN';
+export { joinTokens } from './joinTokens';
+export { DEFAULT_PUNCTUATION_STRIP_SET_EN, matchENKeyword, normalizeENKeyword } from './enKeyword';
+export { compareBreaksLexicographically } from './compare';
+

client/src/features/textWrap/core/joinTokens.ts

@@ -0,0 +1,37 @@
+import type { Token } from './types';
+
+/**
+ * 从 token 区间 `[start..end)` 重组回文本（跨端口径）。
+ *
+ * - 默认：用单空格 join（适用于 whitespacePolicy=NORMALIZE）
+ * - 若传入 rawSeparators：按原始分隔符拼接（适用于 whitespacePolicy=PRESERVE）
+ *
+ * 说明：
+ * - `start/end` 为半开区间
+ * - 空区间返回空字符串；上层需要用硬约束避免空行
+ */
+export function joinTokens(tokens: Token[], start: number, end: number, rawSeparators?: string[]): string {
+  const s = Math.max(0, start | 0);
+  const e = Math.max(0, end | 0);
+  if (!Array.isArray(tokens) || tokens.length === 0) return '';
+  if (s >= e) return '';
+
+  const slice = tokens.slice(s, e).map((t) => t.text);
+  if (!rawSeparators) {
+    return slice.join(' ');
+  }
+
+  // rawSeparators[i] 表示 tokens[i] 与 tokens[i+1] 之间的分隔符
+  // 这里只实现最小可用：若 separators 缺失则回退到单空格。
+  let out = '';
+  for (let idx = s; idx < e; idx++) {
+    const t = tokens[idx];
+    if (!t) continue;
+    out += t.text;
+    if (idx < e - 1) {
+      out += rawSeparators[idx] ?? ' ';
+    }
+  }
+  return out;
+}
+

client/src/features/textWrap/core/normalizeWhitespace.ts

@@ -0,0 +1,28 @@
+import type { NormalizeWhitespaceResult, WhitespacePolicy } from './types';
+
+/**
+ * 空白归一化（跨端口径）
+ *
+ * - NORMALIZE：折叠连续空白为单空格，并去首尾空白
+ * - PRESERVE：仅去首尾空白（内部空白保持原样）
+ *
+ * 注意：该函数会改变输入文本（至少会 trim），必须作为“算法契约”的一部分固定下来。
+ */
+export function normalizeWhitespace(text: string, policy: WhitespacePolicy = 'NORMALIZE'): NormalizeWhitespaceResult {
+  const input = String(text ?? '');
+
+  if (policy === 'PRESERVE') {
+    const trimmed = input.trim();
+    // 只要发生 trim，或内部存在非单空格的分隔（如 \n/\t/多个空格），都算 hadMultiWhitespace
+    const hadMultiWhitespace = trimmed !== input || /[\t\r\n]/.test(trimmed) || /  +/.test(trimmed);
+    return { normalizedText: trimmed, hadMultiWhitespace };
+  }
+
+  // NORMALIZE：把任意连续空白折叠为 1 个空格，并去首尾空白
+  // 说明：这里使用 \s+ 覆盖空格/换行/制表等；跨端需要保证采用同等语义的实现。
+  const trimmed = input.trim();
+  const collapsed = trimmed.replace(/\s+/g, ' ');
+  const hadMultiWhitespace = collapsed !== input;
+  return { normalizedText: collapsed, hadMultiWhitespace };
+}
+

client/src/features/textWrap/core/tokenizeEN.ts

@@ -0,0 +1,38 @@
+import type { Token } from './types';
+
+/**
+ * EN tokenize（极简派）
+ *
+ * 口径：
+ * - tokens 只包含 WORD，不生成 SPACE token
+ * - 标点视为“词内字符”，不额外拆分（例如 "tired."、"Wait..."、"hello—world" 都是一个 token）
+ * - 断点只允许发生在“词与词之间”（由上层生成 breakpoint 时遵守）
+ *
+ * start/end 索引以 normalizedText 为基准（建议先调用 normalizeWhitespace）。
+ */
+export function tokenizeEN(normalizedText: string): Token[] {
+  const s = String(normalizedText ?? '');
+  if (!s) return [];
+
+  const tokens: Token[] = [];
+
+  // 由于 NORMALIZE 模式下空白都折叠为单空格，这里按空格扫描即可。
+  // 为了稳健性，也允许出现意外多空格（会跳过空段）。
+  let i = 0;
+  const n = s.length;
+
+  while (i < n) {
+    // 跳过空格（或其他空白字符）
+    while (i < n && /\s/.test(s[i]!)) i++;
+    if (i >= n) break;
+
+    const start = i;
+    while (i < n && !/\s/.test(s[i]!)) i++;
+    const end = i;
+
+    tokens.push({ text: s.slice(start, end), start, end });
+  }
+
+  return tokens;
+}
+

client/src/features/textWrap/core/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Text Wrap - core-contract
+ *
+ * 本文件定义“跨端一致的基础口径”所需的最小类型集合。
+ * 注意：这里的索引（start/end）默认以 normalizedText（归一化后的文本）为基准。
+ */
+
+export type Lang = 'TC' | 'EN';
+
+export type WhitespacePolicy = 'NORMALIZE' | 'PRESERVE';
+
+export type Token = {
+  /** token 的原始文本（EN：词；TC：字符簇） */
+  text: string;
+  /** token 在 normalizedText 中的起始索引（包含） */
+  start: number;
+  /** token 在 normalizedText 中的结束索引（不包含） */
+  end: number;
+};
+
+export type NormalizeWhitespaceResult = {
+  /**
+   * 归一化后的文本。
+   * - NORMALIZE：折叠连续空白为单空格，并去首尾空白
+   * - PRESERVE：仅去首尾空白（内部空白保持原样）
+   */
+  normalizedText: string;
+  /** 是否发生过“空白折叠/trim/非单空格分隔”等（用于后续 meta 打点） */
+  hadMultiWhitespace: boolean;
+};
+
+export type CoreConfig = {
+  whitespacePolicy: WhitespacePolicy;
+  /**
+   * EN 关键词命中：两端可剥离的常见标点集合（必须全端一致）。
+   * 来源建议与默认值参考：`设计说明文档/文档换行算法.md`（v1.2.1）2.3.1A-1
+   */
+  punctuationStripSetEN: string[];
+};
+

client/src/features/textWrap/golden/__tests__/golden.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Token } from '../../core/types';
+import { normalizeWhitespace, tokenizeEN } from '../../core/index';
+import { segmentGraphemes } from '../../grapheme/index';
+import { wrapText } from '../../index';
+import { GOLDEN_CASES } from '../fixtures';
+
+function tokenizeTC(normalizedText: string): Token[] {
+  const { clusters } = segmentGraphemes(normalizedText, 'PREFERRED');
+  const tokens: Token[] = [];
+  let idx = 0;
+  for (const c of clusters) {
+    const start = idx;
+    idx += c.length;
+    tokens.push({ text: c, start, end: idx });
+  }
+  return tokens;
+}
+
+async function wrapTextHarness(args: {
+  text: string;
+  lang: 'TC' | 'EN';
+  context: 'APP' | 'WIDGET';
+  availableWidth: number;
+  maxLines: number;
+}): Promise<{ ok: true; lines: string[]; wrappedText: string } | { ok: false; detail: any }> {
+  const out = await wrapText({
+    text: args.text,
+    lang: args.lang,
+    context: args.context,
+    availableWidth: args.availableWidth,
+    maxLines: args.maxLines,
+    fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+    measureWidthImpl: async ({ text }) => text.length,
+    contextProfile: `${args.context}|golden`,
+    lineMode: 'AUTO',
+    debug: true,
+  });
+
+  // wrapText 统一返回成功形态；若进入 SYSTEM_DEFAULT 等兜底，meta 会标记
+  return { ok: true, lines: out.lines, wrappedText: out.wrappedText };
+}
+
+describe('textWrap golden-tests', () => {
+  for (const c of GOLDEN_CASES) {
+    it(`golden:${c.id}`, async () => {
+      const res = await wrapTextHarness({
+        text: c.text,
+        lang: c.lang,
+        context: c.context,
+        availableWidth: c.availableWidth,
+        maxLines: c.maxLines,
+      });
+
+      if (!res.ok) {
+        throw new Error(`golden case failed: ${c.id}\n${JSON.stringify(res.detail, null, 2)}`);
+      }
+      if (res.ok) {
+        expect(res.lines).toEqual(c.expected.lines);
+        expect(res.wrappedText).toBe(c.expected.wrappedText);
+      }
+    });
+  }
+
+  it('property: 确定性（同输入多次调用一致）', async () => {
+    const args = { text: 'I am so tired', lang: 'EN' as const, context: 'APP' as const, availableWidth: 6, maxLines: 2 };
+    const a = await wrapTextHarness(args);
+    const b = await wrapTextHarness(args);
+    const c = await wrapTextHarness(args);
+    expect(a).toEqual(b);
+    expect(b).toEqual(c);
+  });
+
+  it('property: 近似单调性（availableWidth 变小不会让最大行宽变大）', async () => {
+    const base = { text: 'I am so tired', lang: 'EN' as const, context: 'APP' as const, maxLines: 2 };
+    const wide = await wrapTextHarness({ ...base, availableWidth: 20 });
+    const narrow = await wrapTextHarness({ ...base, availableWidth: 7 });
+
+    if (!wide.ok || !narrow.ok) {
+      throw new Error(`property failed: expected both ok\nwide=${JSON.stringify(wide)}\nnarrow=${JSON.stringify(narrow)}`);
+    }
+
+    const maxW = (lines: string[]) => Math.max(...lines.map((s) => s.length));
+    expect(maxW(narrow.lines)).toBeLessThanOrEqual(maxW(wide.lines));
+  });
+
+  it('property: maxLines 不变差（maxLines 增加不应从可解变无解）', async () => {
+    const base = { text: 'I am so tired', lang: 'EN' as const, context: 'APP' as const, availableWidth: 7 };
+    const a = await wrapTextHarness({ ...base, maxLines: 2 });
+    const b = await wrapTextHarness({ ...base, maxLines: 3 });
+
+    expect(a.ok).toBe(true);
+    expect(b.ok).toBe(true);
+  });
+});
+

client/src/features/textWrap/golden/fixtures.ts

@@ -0,0 +1,56 @@
+export type GoldenCase = {
+  id: string;
+  text: string;
+  lang: 'TC' | 'EN';
+  context: 'APP' | 'WIDGET';
+  availableWidth: number;
+  maxLines: number;
+  expected: { lines: string[]; wrappedText: string };
+};
+
+/**
+ * Golden fixtures（首版最小可运行集）
+ *
+ * 说明：
+ * - APP：测量 mock=string.length，因此 availableWidth 也是“字符数单位”
+ * - WIDGET：widthMode=APPROX，因此 availableWidth 是“token 数单位”
+ */
+export const GOLDEN_CASES: GoldenCase[] = [
+  {
+    id: 'en_app_simple_2lines',
+    text: 'I am so tired',
+    lang: 'EN',
+    context: 'APP',
+    availableWidth: 7,
+    maxLines: 2,
+    expected: { lines: ['I am so', 'tired'], wrappedText: 'I am so\ntired' },
+  },
+  {
+    id: 'en_app_punct_keyword',
+    text: 'but, still ok',
+    lang: 'EN',
+    context: 'APP',
+    availableWidth: 9,
+    maxLines: 2,
+    expected: { lines: ['but,', 'still ok'], wrappedText: 'but,\nstill ok' },
+  },
+  {
+    id: 'tc_app_punct_2lines',
+    text: '我好累，😮‍💨',
+    lang: 'TC',
+    context: 'APP',
+    availableWidth: 6,
+    maxLines: 2,
+    expected: { lines: ['我好累，', '😮‍💨'], wrappedText: '我好累，\n😮‍💨' },
+  },
+  {
+    id: 'tc_widget_approx_2lines',
+    text: '我好累',
+    lang: 'TC',
+    context: 'WIDGET',
+    availableWidth: 2,
+    maxLines: 2,
+    expected: { lines: ['我', '好累'], wrappedText: '我\n好累' },
+  },
+];
+

client/src/features/textWrap/grapheme/__tests__/segmentGraphemes.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import { segmentGraphemes } from '../index';
+
+const REQUIRED_SINGLE_CLUSTER_CASES: Array<{ name: string; input: string }> = [
+  { name: 'ZWJ family', input: '👨‍👩‍👧‍👦' },
+  { name: 'flag', input: '🇸🇬' },
+  { name: 'skin tone', input: '👍🏽' },
+  { name: 'ZWJ + variation', input: '😮‍💨' },
+  { name: 'combining mark', input: 'e\u0301' }, // é（组合形式）
+];
+
+describe('textWrap grapheme-segmentation', () => {
+  it('基础性质：空字符串 -> []', () => {
+    const out = segmentGraphemes('', 'PREFERRED');
+    expect(out.clusters).toEqual([]);
+    expect(out.clusters.join('')).toBe('');
+  });
+
+  it('基础性质：可逆性（clusters.join("") === input）', () => {
+    const input = '我好累😮‍💨';
+    const out = segmentGraphemes(input, 'PREFERRED');
+    expect(out.clusters.join('')).toBe(input);
+  });
+
+  it('基础性质：确定性（同输入同输出）', () => {
+    const input = '👨‍👩‍👧‍👦🇸🇬👍🏽😮‍💨e\u0301';
+    const a = segmentGraphemes(input, 'PREFERRED');
+    const b = segmentGraphemes(input, 'PREFERRED');
+    expect(a).toEqual(b);
+  });
+
+  it('必测样例：在 PREFERRED 下必须“不拆”为单个 cluster', () => {
+    for (const c of REQUIRED_SINGLE_CLUSTER_CASES) {
+      const out = segmentGraphemes(c.input, 'PREFERRED');
+      expect(out.clusters.join('')).toBe(c.input);
+      expect(out.clusters.length).toBe(1);
+      expect(out.clusters[0]).toBe(c.input);
+    }
+  });
+
+  it('必测样例：在强制 FALLBACK 下必须“不拆”为单个 cluster', () => {
+    for (const c of REQUIRED_SINGLE_CLUSTER_CASES) {
+      const out = segmentGraphemes(c.input, 'FALLBACK');
+      expect(out.meta.strategy).toBe('FALLBACK');
+      expect(out.meta.hadFallback).toBe(true);
+      expect(out.clusters.join('')).toBe(c.input);
+      expect(out.clusters.length).toBe(1);
+      expect(out.clusters[0]).toBe(c.input);
+    }
+  });
+
+  it('跨策略一致性：若 Intl.Segmenter 可用，则 PREFERRED 与 FALLBACK 输出应一致', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const hasIntl = typeof (globalThis as any)?.Intl?.Segmenter === 'function';
+    if (!hasIntl) return;
+
+    for (const c of REQUIRED_SINGLE_CLUSTER_CASES) {
+      const preferred = segmentGraphemes(c.input, 'PREFERRED');
+      const fallback = segmentGraphemes(c.input, 'FALLBACK');
+      expect(preferred.clusters).toEqual(fallback.clusters);
+    }
+  });
+});
+

client/src/features/textWrap/grapheme/index.ts

@@ -0,0 +1,9 @@
+export type {
+  GraphemeSegmentationMeta,
+  GraphemeSegmentationMode,
+  GraphemeSegmentationResult,
+  GraphemeSegmentationStrategy,
+} from './types';
+
+export { segmentGraphemes } from './segmentGraphemes';
+

client/src/features/textWrap/grapheme/segmentGraphemes.ts

@@ -0,0 +1,42 @@
+import type { GraphemeSegmentationMode, GraphemeSegmentationResult } from './types';
+import { canUseIntlSegmenter, segmentWithIntlSegmenter } from './strategies/intlSegmenter';
+import { segmentWithFallback } from './strategies/fallback';
+
+/**
+ * 把字符串切分为 grapheme clusters（字符簇）。
+ *
+ * 契约（必须）：
+ * - clusters.join('') === text（不允许丢字符/改顺序）
+ * - text=='' 时 clusters==[]
+ * - 任何异常都必须降级到 fallback（保证可用性）
+ */
+export function segmentGraphemes(text: string, mode: GraphemeSegmentationMode = 'PREFERRED'): GraphemeSegmentationResult {
+  const input = String(text ?? '');
+  if (input === '') {
+    return { clusters: [], meta: { strategy: 'FALLBACK', hadFallback: mode === 'FALLBACK' } };
+  }
+
+  // 强制 fallback
+  if (mode === 'FALLBACK') {
+    const clusters = segmentWithFallback(input);
+    return { clusters, meta: { strategy: 'FALLBACK', hadFallback: true } };
+  }
+
+  // 优先 Intl.Segmenter
+  if (canUseIntlSegmenter()) {
+    try {
+      const clusters = segmentWithIntlSegmenter(input);
+      // 防御：必须可逆
+      if (clusters.length > 0 && clusters.join('') === input) {
+        return { clusters, meta: { strategy: 'INTL_SEGMENTER', hadFallback: false } };
+      }
+      // 若结果异常（空/丢字符），走 fallback
+    } catch {
+      // ignore -> fallback
+    }
+  }
+
+  const clusters = segmentWithFallback(input);
+  return { clusters, meta: { strategy: 'FALLBACK', hadFallback: true } };
+}
+

client/src/features/textWrap/grapheme/strategies/fallback.ts

@@ -0,0 +1,81 @@
+import GraphemeSplitter from 'grapheme-splitter';
+
+/**
+ * fallback 策略：使用 grapheme-splitter 分割 grapheme clusters。
+ *
+ * 选择原因：
+ * - 避免手写不完整的 Unicode 规则导致“漏拆/误拆”
+ * - 作为 Intl.Segmenter 不可用时的稳定兜底
+ *
+ * 注意：
+ * - grapheme-splitter 对少数较新的 emoji ZWJ 序列支持可能不完整（例如 `😮‍💨`）。
+ * - 为满足本项目“至少不拆 ZWJ sequence/VS16/肤色修饰符/组合字符”的最低要求，这里做一层确定性的后处理合并。
+ */
+export function segmentWithFallback(text: string): string[] {
+  const splitter = new GraphemeSplitter();
+  const raw = splitter.splitGraphemes(text);
+  return mergeFallbackClusters(raw);
+}
+
+const ZWJ = '\u200D';
+
+function firstCodePoint(s: string): number | null {
+  if (!s) return null;
+  const cp = s.codePointAt(0);
+  return typeof cp === 'number' ? cp : null;
+}
+
+function isVariationSelector(cp: number): boolean {
+  // VS15/VS16
+  return cp === 0xfe0e || cp === 0xfe0f;
+}
+
+function isSkinToneModifier(cp: number): boolean {
+  return cp >= 0x1f3fb && cp <= 0x1f3ff;
+}
+
+function isCombiningMark(cp: number): boolean {
+  // 常见 combining marks 范围（覆盖 `e\u0301` 等）
+  return (
+    (cp >= 0x0300 && cp <= 0x036f) ||
+    (cp >= 0x1ab0 && cp <= 0x1aff) ||
+    (cp >= 0x1dc0 && cp <= 0x1dff) ||
+    (cp >= 0x20d0 && cp <= 0x20ff) ||
+    (cp >= 0xfe20 && cp <= 0xfe2f)
+  );
+}
+
+/**
+ * 对 fallback 输出做“最低可用”合并：
+ * - 若上一个 cluster 以 ZWJ 结尾，则必须与下一个合并（ZWJ sequence）
+ * - 若下一个 cluster 以 VS/肤色修饰符/combining mark 开头，也与上一个合并
+ *
+ * 目标：满足文档列出的“不拆”组合要求，且行为完全确定性。
+ */
+function mergeFallbackClusters(raw: string[]): string[] {
+  if (!raw.length) return raw;
+
+  const out: string[] = [];
+  let buf = raw[0] ?? '';
+
+  for (let i = 1; i < raw.length; i++) {
+    const next = raw[i] ?? '';
+    const nextCp = firstCodePoint(next);
+
+    const shouldMerge =
+      buf.endsWith(ZWJ) ||
+      (nextCp !== null && (isVariationSelector(nextCp) || isSkinToneModifier(nextCp) || isCombiningMark(nextCp)));
+
+    if (shouldMerge) {
+      buf += next;
+      continue;
+    }
+
+    out.push(buf);
+    buf = next;
+  }
+
+  out.push(buf);
+  return out;
+}
+

client/src/features/textWrap/grapheme/strategies/intlSegmenter.ts

@@ -0,0 +1,28 @@
+/**
+ * Intl.Segmenter 策略（优先）
+ *
+ * 注意：不同 JS 引擎/版本对 Intl.Segmenter 的支持可能不同，调用方必须捕获异常并降级。
+ */
+
+export function canUseIntlSegmenter(): boolean {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Seg = (globalThis as any)?.Intl?.Segmenter;
+  return typeof Seg === 'function';
+}
+
+export function segmentWithIntlSegmenter(text: string): string[] {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Segmenter = (globalThis as any).Intl.Segmenter as new (locales?: string | string[], options?: any) => any;
+
+  // 用 zh-Hant 仅用于选择合适的 locale；grapheme 分割应与语言本身关系不大，但保持固定输入更易对齐跨端。
+  const seg = new Segmenter('zh-Hant', { granularity: 'grapheme' });
+  const it = seg.segment(text);
+
+  const clusters: string[] = [];
+  for (const part of it) {
+    // part: { segment: string, index: number, input: string, isWordLike?: boolean }
+    clusters.push(part.segment);
+  }
+  return clusters;
+}
+

client/src/features/textWrap/grapheme/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Text Wrap - grapheme-segmentation
+ *
+ * 本模块只负责把字符串切成“字符簇（grapheme clusters）”数组。
+ * 后续 TC 换行断点只能发生在 clusters 边界。
+ */
+
+export type GraphemeSegmentationMode = 'PREFERRED' | 'FALLBACK';
+
+export type GraphemeSegmentationStrategy = 'INTL_SEGMENTER' | 'FALLBACK';
+
+export type GraphemeSegmentationMeta = {
+  strategy: GraphemeSegmentationStrategy;
+  hadFallback: boolean;
+};
+
+export type GraphemeSegmentationResult = {
+  clusters: string[];
+  meta: GraphemeSegmentationMeta;
+};
+

client/src/features/textWrap/index.ts

@@ -0,0 +1,4 @@
+export type { WrapTextConstraints, WrapTextInput, WrapTextMeta, WrapTextOutput } from './types';
+
+export { wrapText } from './wrapText';
+

client/src/features/textWrap/measure/__tests__/widthMeasurement.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeasureWidthImpl } from '../types';
+import { MissingFontSpecError } from '../errors';
+import { buildFontSpecKey } from '../fontSpecKey';
+import { measureSliceWidthCached } from '../measureSliceWidthCached';
+import { measureWidthCached } from '../measureWidthCached';
+
+describe('textWrap width-measurement', () => {
+  it('buildFontSpecKey: 缺字段必须报错（简体中文）', () => {
+    expect(() => buildFontSpecKey({ fontFamily: 'PingFangSC-Regular', fontWeight: '400' } as any)).toThrow(
+      MissingFontSpecError
+    );
+  });
+
+  it('measureWidthCached: 未提供测量能力 -> approx + WIDTH_UNKNOWN', async () => {
+    const res = await measureWidthCached({
+      text: 'hello',
+      context: 'WIDGET',
+      contextProfile: 'WIDGET',
+      fontSpec: null,
+      measureWidthImpl: undefined,
+    });
+    expect(res.width).toBeNull();
+    expect(res.meta).toEqual({ isApprox: true, reason: 'WIDTH_UNKNOWN' });
+  });
+
+  it('measureWidthCached: 同 key 命中缓存（不会重复调用底层测量）', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+
+    const a = await measureWidthCached({
+      text: 'abc',
+      context: 'APP',
+      contextProfile: 'APP|ios',
+      fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+      measureWidthImpl: impl,
+    });
+    const b = await measureWidthCached({
+      text: 'abc',
+      context: 'APP',
+      contextProfile: 'APP|ios',
+      fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+      measureWidthImpl: impl,
+    });
+
+    expect(a.width).toBe(3);
+    expect(b.width).toBe(3);
+    expect(impl).toHaveBeenCalledTimes(1);
+  });
+
+  it('measureWidthCached: 测量抛错 -> approx + MEASURE_FAILED', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async () => {
+      throw new Error('boom');
+    });
+
+    const res = await measureWidthCached({
+      text: 'abc',
+      context: 'APP',
+      contextProfile: 'APP|ios|throw',
+      fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+      measureWidthImpl: impl,
+    });
+
+    expect(res.width).toBeNull();
+    expect(res.meta).toEqual({ isApprox: true, reason: 'MEASURE_FAILED' });
+  });
+
+  it('measureSliceWidthCached: 同 sliceKey 命中缓存', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+
+    const tokens = [
+      { text: 'I', start: 0, end: 1 },
+      { text: 'am', start: 2, end: 4 },
+      { text: 'tired', start: 5, end: 10 },
+    ];
+
+    const a = await measureSliceWidthCached({
+      tokens: tokens as any,
+      start: 0,
+      end: 2,
+      context: 'APP',
+      contextProfile: 'APP|ios',
+      fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+      measureWidthImpl: impl,
+    });
+    const b = await measureSliceWidthCached({
+      tokens: tokens as any,
+      start: 0,
+      end: 2,
+      context: 'APP',
+      contextProfile: 'APP|ios',
+      fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+      measureWidthImpl: impl,
+    });
+
+    expect(a.width).toBe('I am'.length);
+    expect(b.width).toBe('I am'.length);
+    expect(impl).toHaveBeenCalledTimes(1);
+  });
+});
+

client/src/features/textWrap/measure/cache.ts

@@ -0,0 +1,62 @@
+/**
+ * Text Wrap - width-measurement 缓存
+ *
+ * 要求：
+ * - 模块级常驻缓存（跨调用复用）
+ * - 有容量上限（避免内存无限增长）
+ * - Key 必须确定性（由上层拼接传入）
+ *
+ * 说明：
+ * - 这里实现一个最小 LRU：Map 维护插入顺序；get 时“刷新”为最新。
+ * - 缓存 value 允许是 Promise，以便并发请求去重（同 key 只测一次）。
+ */
+
+export class LruCache<V> {
+  private readonly maxSize: number;
+  private readonly map: Map<string, V>;
+
+  constructor(maxSize: number) {
+    if (!Number.isFinite(maxSize) || maxSize <= 0) {
+      throw new Error('LRU 缓存 maxSize 必须为正数。');
+    }
+    this.maxSize = Math.floor(maxSize);
+    this.map = new Map();
+  }
+
+  get(key: string): V | undefined {
+    const v = this.map.get(key);
+    if (v === undefined) return undefined;
+    // 刷新为最新
+    this.map.delete(key);
+    this.map.set(key, v);
+    return v;
+  }
+
+  set(key: string, value: V): void {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    }
+    this.map.set(key, value);
+
+    if (this.map.size > this.maxSize) {
+      // 淘汰最旧的
+      const oldestKey = this.map.keys().next().value as string | undefined;
+      if (oldestKey !== undefined) {
+        this.map.delete(oldestKey);
+      }
+    }
+  }
+
+  delete(key: string): void {
+    this.map.delete(key);
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  size(): number {
+    return this.map.size;
+  }
+}
+

client/src/features/textWrap/measure/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Text Wrap - width-measurement 错误定义
+ *
+ * 约束：fontSpec 缺字段必须直接报错（简体中文），禁止隐式默认值。
+ */
+
+export class MissingFontSpecError extends Error {
+  readonly name = 'MissingFontSpecError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export function buildMissingFontSpecMessage(missingFields: string[]): string {
+  const fields = missingFields.join(', ');
+  return `fontSpec 缺少必填字段：${fields}。请在调用 wrapText() 时补齐 fontSpec（fontFamily/fontWeight/fontSize），禁止在测量层使用隐式默认值。`;
+}
+

client/src/features/textWrap/measure/fontSpecKey.ts

@@ -0,0 +1,32 @@
+import type { FontSpec } from './types';
+import { MissingFontSpecError, buildMissingFontSpecMessage } from './errors';
+
+/**
+ * 校验 fontSpec 必填字段。
+ * 约束：缺失字段必须报错（简体中文），避免跨端漂移。
+ */
+export function assertFontSpecComplete(fontSpec: Partial<FontSpec> | undefined | null): asserts fontSpec is FontSpec {
+  if (!fontSpec) {
+    throw new MissingFontSpecError(buildMissingFontSpecMessage(['fontFamily', 'fontWeight', 'fontSize']));
+  }
+
+  const missing: string[] = [];
+  if (!fontSpec.fontFamily) missing.push('fontFamily');
+  if (!fontSpec.fontWeight) missing.push('fontWeight');
+  if (fontSpec.fontSize === undefined || fontSpec.fontSize === null) missing.push('fontSize');
+
+  if (missing.length) throw new MissingFontSpecError(buildMissingFontSpecMessage(missing));
+  if (!Number.isFinite(fontSpec.fontSize)) {
+    throw new MissingFontSpecError('fontSpec.fontSize 必须是有限数值（number）。请检查调用 wrapText() 时传入的 fontSize。');
+  }
+}
+
+/**
+ * 生成 fontSpecKey（确定性）。
+ * 规则：`fontFamily|fontWeight|fontSize`（顺序固定）
+ */
+export function buildFontSpecKey(fontSpec: Partial<FontSpec> | undefined | null): string {
+  assertFontSpecComplete(fontSpec);
+  return `${fontSpec.fontFamily}|${fontSpec.fontWeight}|${String(fontSpec.fontSize)}`;
+}
+

client/src/features/textWrap/measure/index.ts

@@ -0,0 +1,16 @@
+export type {
+  ContextProfile,
+  FontSpec,
+  MeasureMeta,
+  MeasureReason,
+  MeasureResult,
+  MeasureWidthImpl,
+  TextWrapContext,
+} from './types';
+
+export { MissingFontSpecError } from './errors';
+export { assertFontSpecComplete, buildFontSpecKey } from './fontSpecKey';
+export { defaultMeasureWidthImpl } from './measureWidthImpl';
+export { measureWidthCached } from './measureWidthCached';
+export { measureSliceWidthCached } from './measureSliceWidthCached';
+

client/src/features/textWrap/measure/measureSliceWidthCached.ts

@@ -0,0 +1,105 @@
+import type { ContextProfile, FontSpec, MeasureResult, MeasureWidthImpl, TextWrapContext } from './types';
+import type { Token } from '../core/types';
+import { LruCache } from './cache';
+import { assertFontSpecComplete, buildFontSpecKey } from './fontSpecKey';
+import { joinTokens } from '../core/joinTokens';
+import { measureWidthCached } from './measureWidthCached';
+
+// 切片缓存：同一 (start,end,fontSpecKey,contextProfile) 的宽度只测一次
+const sliceWidthCache = new LruCache<Promise<number>>(4000);
+
+function fnv1a32(input: string): string {
+  // 32-bit FNV-1a（确定性、实现简单；用于缓存 key 避免过长）
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    // hash *= 16777619（用位运算模拟 32-bit 溢出）
+    hash = (hash + (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function buildSliceKey(args: {
+  contextProfile: ContextProfile;
+  fontSpecKey: string;
+  start: number;
+  end: number;
+  sliceTextHash: string;
+}): string {
+  // 注意：必须包含 sliceText 的信息，否则不同文本的相同 (start,end) 会发生跨文本串缓存
+  return `${args.contextProfile}|${args.fontSpecKey}|${args.start}|${args.end}|${args.sliceTextHash}`;
+}
+
+/**
+ * 测量 token 切片 `[start..end)` 的宽度（带缓存）。
+ *
+ * - 切片文本通过 `joinTokens()` 生成（保证与 core-contract 的重组口径一致）
+ * - 内部复用 `measureWidthCached` 的降级语义
+ */
+export async function measureSliceWidthCached(args: {
+  tokens: Token[];
+  start: number;
+  end: number;
+  context: TextWrapContext;
+  contextProfile: ContextProfile;
+  fontSpec?: Partial<FontSpec> | null;
+  measureWidthImpl?: MeasureWidthImpl;
+  widgetEnableMeasure?: boolean;
+  rawSeparators?: string[];
+}): Promise<MeasureResult> {
+  const enabled =
+    typeof args.measureWidthImpl === 'function' && (args.context === 'APP' || args.widgetEnableMeasure === true);
+
+  if (!enabled) {
+    // 不启用测量时直接走 width=null（保持与 measureWidthCached 一致）
+    return { width: null, meta: { isApprox: true, reason: 'WIDTH_UNKNOWN' } };
+  }
+
+  assertFontSpecComplete(args.fontSpec);
+  const fontSpecKey = buildFontSpecKey(args.fontSpec);
+  const sliceText = joinTokens(args.tokens, args.start, args.end, args.rawSeparators);
+  const key = buildSliceKey({
+    contextProfile: args.contextProfile,
+    fontSpecKey,
+    start: args.start,
+    end: args.end,
+    sliceTextHash: fnv1a32(sliceText),
+  });
+
+  const cached = sliceWidthCache.get(key);
+  if (cached) {
+    try {
+      const w = await cached;
+      return { width: w, meta: { isApprox: false } };
+    } catch {
+      return { width: null, meta: { isApprox: true, reason: 'MEASURE_FAILED' } };
+    }
+  }
+
+  const promise = (async () => {
+    const res = await measureWidthCached({
+      text: sliceText,
+      context: args.context,
+      contextProfile: args.contextProfile,
+      fontSpec: args.fontSpec,
+      measureWidthImpl: args.measureWidthImpl,
+      widgetEnableMeasure: args.widgetEnableMeasure,
+    });
+
+    if (res.width === null) {
+      throw new Error('切片测量失败或不可用。');
+    }
+    return res.width;
+  })();
+
+  sliceWidthCache.set(key, promise);
+
+  try {
+    const w = await promise;
+    return { width: w, meta: { isApprox: false } };
+  } catch {
+    sliceWidthCache.delete(key);
+    return { width: null, meta: { isApprox: true, reason: 'MEASURE_FAILED' } };
+  }
+}
+

client/src/features/textWrap/measure/measureWidthCached.ts

@@ -0,0 +1,110 @@
+import type { ContextProfile, FontSpec, MeasureResult, MeasureWidthImpl, TextWrapContext } from './types';
+import { LruCache } from './cache';
+import { assertFontSpecComplete, buildFontSpecKey } from './fontSpecKey';
+
+// 模块级常驻缓存（两级）
+const textWidthCache = new LruCache<Promise<number>>(2000);
+const loggedMeasureFailures = new Set<string>();
+
+function buildTextKey(args: { contextProfile: ContextProfile; fontSpecKey: string; text: string }): string {
+  // key 拼接规则必须确定性：<contextProfile>|<fontSpecKey>|<text>
+  return `${args.contextProfile}|${args.fontSpecKey}|${args.text}`;
+}
+
+function isValidWidth(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+
+/**
+ * 测量文本宽度（带缓存）。
+ *
+ * 约束：
+ * - 若启用测量（提供 measureWidthImpl），fontSpec 必须完整；缺字段直接报错（简体中文）
+ * - 若不启用测量（measureWidthImpl 缺失或 context=WIDGET 且明确不启用），进入 approx mode：width=null
+ */
+export async function measureWidthCached(args: {
+  text: string;
+  context: TextWrapContext;
+  contextProfile: ContextProfile;
+  fontSpec?: Partial<FontSpec> | null;
+  measureWidthImpl?: MeasureWidthImpl;
+  /** WIDGET 场景是否启用测量；默认 false（未启用即 WIDTH_UNKNOWN） */
+  widgetEnableMeasure?: boolean;
+}): Promise<MeasureResult> {
+  const text = String(args.text ?? '');
+
+  const enabled =
+    typeof args.measureWidthImpl === 'function' && (args.context === 'APP' || args.widgetEnableMeasure === true);
+
+  if (!enabled) {
+    return { width: null, meta: { isApprox: true, reason: 'WIDTH_UNKNOWN' } };
+  }
+
+  // 启用测量时：fontSpec 缺字段必须报错
+  const fontSpec = args.fontSpec;
+  assertFontSpecComplete(fontSpec);
+  const fontSpecKey = buildFontSpecKey(fontSpec);
+  const key = buildTextKey({ contextProfile: args.contextProfile, fontSpecKey, text });
+
+  const cached = textWidthCache.get(key);
+  if (cached) {
+    try {
+      const w = await cached;
+      return isValidWidth(w) ? { width: w, meta: { isApprox: false } } : { width: null, meta: { isApprox: true, reason: 'MEASURE_FAILED' } };
+    } catch {
+      if (__DEV__ && !loggedMeasureFailures.has(key)) {
+        loggedMeasureFailures.add(key);
+        console.log('[TextWrap][Measure] measureWidthCached: 命中缓存但 Promise 失败（MEASURE_FAILED）', {
+          context: args.context,
+          contextProfile: args.contextProfile,
+          fontSpec: args.fontSpec,
+          textPreview: text.slice(0, 80),
+          textLength: text.length,
+        });
+      }
+      return { width: null, meta: { isApprox: true, reason: 'MEASURE_FAILED' } };
+    }
+  }
+
+  const promise = (async () => {
+    try {
+      const w = await args.measureWidthImpl!({
+        text,
+        context: args.context,
+        contextProfile: args.contextProfile,
+        fontSpec,
+      });
+      if (!isValidWidth(w)) {
+        throw new Error('测量结果非法（必须为有限且非负的 number）。');
+      }
+      return w;
+    } catch (error) {
+      if (__DEV__ && !loggedMeasureFailures.has(key)) {
+        loggedMeasureFailures.add(key);
+        console.log('[TextWrap][Measure] measureWidthImpl 抛错（MEASURE_FAILED）', {
+          context: args.context,
+          contextProfile: args.contextProfile,
+          fontSpec,
+          textPreview: text.slice(0, 80),
+          textLength: text.length,
+          errorName: (error as any)?.name,
+          errorMessage: String((error as any)?.message ?? error),
+          errorStack: (error as any)?.stack,
+        });
+      }
+      throw error;
+    }
+  })();
+
+  textWidthCache.set(key, promise);
+
+  try {
+    const w = await promise;
+    return { width: w, meta: { isApprox: false } };
+  } catch {
+    // 若失败，删除缓存，避免缓存住失败结果
+    textWidthCache.delete(key);
+    return { width: null, meta: { isApprox: true, reason: 'MEASURE_FAILED' } };
+  }
+}
+

client/src/features/textWrap/measure/measureWidthImpl.ts

@@ -0,0 +1,66 @@
+import type { FontSpec, MeasureWidthImpl } from './types';
+
+/**
+ * 默认测量实现（成熟方案）：react-native-text-size
+ *
+ * 注意：
+ * - 该库的 `measure` 是 Promise 异步接口，本模块以 async 方式对齐。
+ * - 为避免在测试/Node 环境直接 require `react-native` 造成崩溃，这里使用“延迟加载 + 捕获异常”。
+ */
+
+type TextSizeMeasureParams = {
+  text: string;
+  width?: number;
+  fontFamily?: string;
+  fontSize?: number;
+  fontWeight?: string;
+  allowFontScaling?: boolean;
+  usePreciseWidth?: boolean;
+};
+
+type TextSizeMeasureResult = { width: number };
+
+function loadReactNativeTextSize(): {
+  measure: (params: TextSizeMeasureParams) => Promise<TextSizeMeasureResult>;
+} {
+  // 使用 require 确保 Metro 能解析并打包该原生模块（动态 import 在某些环境下无法被正确解析）
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+  const mod: any = require('react-native-text-size');
+  return mod?.default ?? mod;
+}
+
+function toTextSizeFontSpecs(fontSpec: FontSpec): Pick<TextSizeMeasureParams, 'fontFamily' | 'fontSize' | 'fontWeight'> {
+  return {
+    fontFamily: fontSpec.fontFamily,
+    fontSize: fontSpec.fontSize,
+    fontWeight: fontSpec.fontWeight,
+  };
+}
+
+/**
+ * 默认测量函数（可替换/可注入）。
+ * - width 约束设为极大值，避免自动换行影响“单行宽度”测量
+ * - usePreciseWidth=true，取更精确的宽度（开销更大，但对本算法更稳定）
+ */
+export const defaultMeasureWidthImpl: MeasureWidthImpl = async ({ text, fontSpec }) => {
+  const TextSize = loadReactNativeTextSize();
+  if (!TextSize || typeof TextSize.measure !== 'function') {
+    // 典型原因：在 Expo Go 中运行，或没有使用包含该原生模块的 Development Build。
+    // 这里抛出更明确的错误，方便上层捕获并在 meta.reason=MEASURE_FAILED 时看到根因。
+    throw new Error(
+      [
+        'react-native-text-size 原生模块不可用：TextSize.measure 不是函数。',
+        '请确认你不是在 Expo Go 里运行；需要使用包含该原生模块的 Development Build（expo-dev-client / expo run:ios / EAS dev build）。',
+      ].join(' '),
+    );
+  }
+  const res = await TextSize.measure({
+    text,
+    width: 1_000_000_000,
+    usePreciseWidth: true,
+    allowFontScaling: true,
+    ...toTextSizeFontSpecs(fontSpec),
+  });
+  return res.width;
+};
+

client/src/features/textWrap/measure/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Text Wrap - width-measurement
+ *
+ * 本模块负责：
+ * - 宽度测量（可注入实现）
+ * - 两级缓存（文本/切片）
+ * - 测量失败时的确定性降级（approx mode）
+ *
+ * 注意：真实测量（如 react-native-text-size）通常是异步 Promise，本模块统一使用 async 形式对齐实际能力。
+ */
+
+export type TextWrapContext = 'APP' | 'WIDGET';
+
+export type FontSpec = {
+  fontSize: number;
+  fontFamily: string;
+  fontWeight: string;
+};
+
+/**
+ * 用于区分不同测量语境（缓存隔离）。
+ * 口径建议：`APP|<platform>|<scale?>` 或 `WIDGET|<widgetSize?>`
+ */
+export type ContextProfile = string;
+
+export type MeasureReason = 'WIDTH_UNKNOWN' | 'MEASURE_FAILED';
+
+export type MeasureMeta = {
+  isApprox: boolean;
+  reason?: MeasureReason;
+};
+
+export type MeasureResult = {
+  width: number | null;
+  meta: MeasureMeta;
+};
+
+/**
+ * 可注入的测量实现（成熟方法推荐用原生/离屏测量库）。
+ * 约定：返回值必须是“有限且非负”的 number，否则视为测量失败。
+ */
+export type MeasureWidthImpl = (args: {
+  text: string;
+  context: TextWrapContext;
+  fontSpec: FontSpec;
+  contextProfile: ContextProfile;
+}) => Promise<number>;
+

client/src/features/textWrap/overflow/__tests__/overflowFallback.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeasureWidthImpl } from '../../measure/types';
+import { applyOverflowFallback } from '../fallback';
+
+function t(text: string, start: number) {
+  return { text, start, end: start + text.length };
+}
+
+describe('textWrap overflow-fallback', () => {
+  it('SYSTEM_DEFAULT：仍返回单行，但 meta 标记 SYSTEM_DEFAULT', async () => {
+    const res = await applyOverflowFallback({
+      tokens: [t('I', 0), t('am', 2), t('tired', 5)],
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 10,
+      maxLines: 2,
+      overflowMode: 'SYSTEM_DEFAULT',
+      ellipsisToken: '…',
+      reason: 'NO_CANDIDATE',
+      partialLayout: null,
+    });
+
+    expect(res.lines.length).toBe(1);
+    expect(res.meta.fallback_type).toBe('SYSTEM_DEFAULT');
+    expect(res.meta.overflow_type).toBe('NONE');
+  });
+
+  it('CLIP：截断到 maxLines', async () => {
+    const res = await applyOverflowFallback({
+      tokens: [t('a', 0), t('b', 2), t('c', 4)],
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 10,
+      maxLines: 2,
+      overflowMode: 'CLIP',
+      ellipsisToken: '…',
+      reason: 'TOO_LONG',
+      partialLayout: {
+        breaks: [1, 2],
+        lines: [
+          { start: 0, end: 1, text: 'a' },
+          { start: 1, end: 2, text: 'b' },
+          // 造一个“未覆盖到 N”的 partial，触发 overflow
+          { start: 2, end: 2, text: 'c' },
+        ],
+      },
+    });
+
+    expect(res.lines).toEqual(['a', 'b']);
+    expect(res.meta.overflow_type).toBe('CLIP');
+  });
+
+  it('ELLIPSIS：清理末尾空白与 TC 末尾标点（不输出 \"  …\" / \"，…\"）', async () => {
+    const res = await applyOverflowFallback({
+      tokens: [t('我', 0), t('好', 1), t('累', 2), t('，', 3)],
+      lang: 'TC',
+      context: 'WIDGET',
+      availableWidth: 10,
+      maxLines: 1,
+      overflowMode: 'ELLIPSIS',
+      ellipsisToken: '…',
+      reason: 'NO_CANDIDATE',
+      partialLayout: {
+        breaks: [],
+        // 造一个“未覆盖到 N”的 partial，触发 overflow
+        lines: [{ start: 0, end: 3, text: '我好累，  ' }],
+      },
+      tcPunctuations: ['，'],
+    });
+
+    expect(res.lines[0]).toBe('我好累…');
+    expect(res.meta.overflow_type).toBe('ELLIPSIS');
+  });
+
+  it('ELLIPSIS：可测量时，超宽则按 token 回退直到不超宽', async () => {
+    // mock：含省略号时宽度=100，否则宽度=文本长度
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => (text.includes('…') ? 100 : text.length));
+
+    const res = await applyOverflowFallback({
+      tokens: [t('I', 0), t('am', 2), t('so', 5), t('tired', 8)],
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 10,
+      maxLines: 1,
+      overflowMode: 'ELLIPSIS',
+      ellipsisToken: '…',
+      reason: 'NO_CANDIDATE',
+      partialLayout: {
+        breaks: [],
+        // 造一个“未覆盖到 N”的 partial，触发 overflow
+        lines: [{ start: 0, end: 3, text: 'I am so' }],
+      },
+      measure: {
+        context: 'APP',
+        contextProfile: 'APP|ios|ellipsis',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+      },
+    });
+
+    // 因为任何带 ellipsis 的测量都超宽，这里会一路回退到空串 + ellipsis
+    expect(res.lines[0]).toBe('…');
+    expect(res.meta.overflow_type).toBe('ELLIPSIS');
+  });
+});
+

client/src/features/textWrap/overflow/ellipsis.ts

@@ -0,0 +1,108 @@
+import type { Token } from '../core/types';
+import { joinTokens } from '../core/joinTokens';
+import { measureWidthCached } from '../measure/measureWidthCached';
+
+import type { ApplyOverflowFallbackInput } from './types';
+
+const DEFAULT_TC_PUNCTS = ['，', '。', '！', '？', '；', '：', '、'];
+
+export function cleanLineBeforeEllipsis(line: string, lang: 'TC' | 'EN', tcPunctuations?: string[]): string {
+  const s = String(line ?? '');
+  const trimmed = s.replace(/\s+$/g, '');
+  if (trimmed === '') return '';
+
+  if (lang === 'TC') {
+    const puncts = new Set(tcPunctuations && tcPunctuations.length > 0 ? tcPunctuations : DEFAULT_TC_PUNCTS);
+    const last = trimmed.slice(-1);
+    if (puncts.has(last)) return trimmed.slice(0, -1);
+  }
+
+  return trimmed;
+}
+
+async function measureIfPossible(args: {
+  text: string;
+  input: ApplyOverflowFallbackInput;
+}): Promise<number | null> {
+  const { input, text } = args;
+  if (!input.measure) return null;
+
+  const enabled =
+    typeof input.measure.measureWidthImpl === 'function' &&
+    (input.measure.context === 'APP' || input.measure.widgetEnableMeasure === true);
+
+  if (!enabled) return null;
+
+  const res = await measureWidthCached({
+    text,
+    context: input.measure.context,
+    contextProfile: input.measure.contextProfile,
+    fontSpec: input.measure.fontSpec,
+    measureWidthImpl: input.measure.measureWidthImpl,
+    widgetEnableMeasure: input.measure.widgetEnableMeasure,
+  });
+
+  return res.width;
+}
+
+/**
+ * 给最后一行加省略号，并在可测量时保证不超宽：
+ * - EN 回退单位：整词（token）
+ * - TC 回退单位：grapheme（token）
+ */
+export async function applyEllipsisToLastLine(args: {
+  input: ApplyOverflowFallbackInput;
+  baseLines: Array<{ start: number; end: number; text: string }>;
+}): Promise<{ lines: string[] }> {
+  const { input } = args;
+  const maxLines = Math.max(1, input.maxLines | 0);
+  const lines = args.baseLines.slice(0, maxLines);
+  if (lines.length === 0) return { lines: [] };
+
+  const lastIdx = lines.length - 1;
+  const last = lines[lastIdx]!;
+
+  // 先按规则清理，再拼接 ellipsisToken
+  const cleaned = cleanLineBeforeEllipsis(last.text, input.lang, input.tcPunctuations);
+  let candidateText = `${cleaned}${input.ellipsisToken}`;
+
+  // 若无测量能力：直接输出（确定性）
+  const measured = await measureIfPossible({ text: candidateText, input });
+  if (measured === null) {
+    const out = lines.map((l, idx) => (idx === lastIdx ? candidateText : l.text));
+    return { lines: out };
+  }
+
+  // 有测量能力：若超宽则按 token 回退
+  if (measured <= input.availableWidth) {
+    const out = lines.map((l, idx) => (idx === lastIdx ? candidateText : l.text));
+    return { lines: out };
+  }
+
+  // 回退：逐步减少最后一行 token 数再加省略号
+  let end = last.end;
+  const start = last.start;
+  let foundFit = false;
+  while (end > start) {
+    end -= 1;
+    const base = joinTokens(input.tokens, start, end);
+    const cleaned2 = cleanLineBeforeEllipsis(base, input.lang, input.tcPunctuations);
+    const nextCandidate = `${cleaned2}${input.ellipsisToken}`;
+    const w = await measureIfPossible({ text: nextCandidate, input });
+    if (w !== null && w <= input.availableWidth) {
+      candidateText = nextCandidate;
+      foundFit = true;
+      break;
+    }
+  }
+
+  // 若连“仅省略号”都无法满足宽度（极窄场景），也必须给出确定性输出：直接输出 ellipsisToken
+  // 注意：这可能仍然超宽，但已是最小可表达形式；上层可通过 meta 做治理。
+  if (!foundFit) {
+    candidateText = input.ellipsisToken;
+  }
+
+  const out = lines.map((l, idx) => (idx === lastIdx ? candidateText : l.text));
+  return { lines: out };
+}
+

client/src/features/textWrap/overflow/fallback.ts

@@ -0,0 +1,86 @@
+import type { Token } from '../core/types';
+import { joinTokens } from '../core/joinTokens';
+
+import { applyEllipsisToLastLine } from './ellipsis';
+import type { ApplyOverflowFallbackInput, ApplyOverflowFallbackResult, PartialLayoutInput, PartialLayoutLine } from './types';
+
+function nTokens(tokens: Token[]): number {
+  return Array.isArray(tokens) ? tokens.length : 0;
+}
+
+function coversToEnd(partial: PartialLayoutInput | null | undefined, n: number): boolean {
+  if (!partial || !Array.isArray(partial.lines) || partial.lines.length === 0) return false;
+  const last = partial.lines[partial.lines.length - 1];
+  return (last?.end ?? -1) === n;
+}
+
+function buildLinesFromPartial(args: {
+  tokens: Token[];
+  partial?: PartialLayoutInput | null;
+  maxLines: number;
+  lang: 'TC' | 'EN';
+}): Array<{ start: number; end: number; text: string }> {
+  const N = nTokens(args.tokens);
+  const maxLines = Math.max(1, args.maxLines | 0);
+  const rawSeparators = args.lang === 'TC' ? Array.from({ length: Math.max(0, N) }, () => '') : undefined;
+
+  if (args.partial && Array.isArray(args.partial.lines) && args.partial.lines.length > 0) {
+    const out: Array<{ start: number; end: number; text: string }> = [];
+    for (const line of args.partial.lines.slice(0, maxLines)) {
+      const start = Math.max(0, line.start | 0);
+      const end = Math.min(N, Math.max(start, line.end | 0));
+      const text = line.text ?? joinTokens(args.tokens, start, end, rawSeparators);
+      out.push({ start, end, text });
+    }
+    return out;
+  }
+
+  // 若没有 partial：把全文当单行 best-effort
+  return [{ start: 0, end: N, text: joinTokens(args.tokens, 0, N, rawSeparators) }];
+}
+
+function toWrapped(lines: string[]): { lines: string[]; wrappedText: string } {
+  const outLines = lines.filter((s) => s !== undefined) as string[];
+  return { lines: outLines, wrappedText: outLines.join('\n') };
+}
+
+function toSingleLine(tokens: Token[]): { lines: string[]; wrappedText: string } {
+  const N = nTokens(tokens);
+  // 注意：这里不知道语言口径，因此 SYSTEM_DEFAULT 的单行文本在上层保证传入“原文”更稳妥。
+  // 为保持最小可用，这里仍使用默认 joinTokens（EN=空格 join，TC=grapheme 之间可能会有空格）。
+  const text = joinTokens(tokens, 0, N);
+  return { lines: [text], wrappedText: text };
+}
+
+export async function applyOverflowFallback(input: ApplyOverflowFallbackInput): Promise<ApplyOverflowFallbackResult> {
+  const tokens = input.tokens ?? [];
+  const N = nTokens(tokens);
+  const maxLines = Math.max(1, input.maxLines | 0);
+
+  const isOverflow = !coversToEnd(input.partialLayout, N);
+
+  // 若其实没有 overflow：直接返回（NONE）
+  if (!isOverflow) {
+    const base = buildLinesFromPartial({ tokens, partial: input.partialLayout, maxLines, lang: input.lang });
+    const { lines, wrappedText } = toWrapped(base.map((l) => l.text));
+    return { lines, wrappedText, meta: { fallback_type: 'NONE', overflow_type: 'NONE', reason: input.reason } };
+  }
+
+  if (input.overflowMode === 'SYSTEM_DEFAULT') {
+    const { lines, wrappedText } = toSingleLine(tokens);
+    return { lines, wrappedText, meta: { fallback_type: 'SYSTEM_DEFAULT', overflow_type: 'NONE', reason: input.reason } };
+  }
+
+  if (input.overflowMode === 'CLIP') {
+    const base = buildLinesFromPartial({ tokens, partial: input.partialLayout, maxLines, lang: input.lang });
+    const { lines, wrappedText } = toWrapped(base.slice(0, maxLines).map((l) => l.text));
+    return { lines, wrappedText, meta: { fallback_type: 'NONE', overflow_type: 'CLIP', reason: input.reason } };
+  }
+
+  // ELLIPSIS
+  const base = buildLinesFromPartial({ tokens, partial: input.partialLayout, maxLines, lang: input.lang });
+  const { lines } = await applyEllipsisToLastLine({ input, baseLines: base.slice(0, maxLines) });
+  const wrapped = toWrapped(lines);
+  return { ...wrapped, meta: { fallback_type: 'NONE', overflow_type: 'ELLIPSIS', reason: input.reason } };
+}
+

client/src/features/textWrap/overflow/index.ts

@@ -0,0 +1,15 @@
+export type {
+  ApplyOverflowFallbackInput,
+  ApplyOverflowFallbackResult,
+  FallbackType,
+  OverflowMeasure,
+  OverflowMode,
+  OverflowReason,
+  OverflowType,
+  PartialLayoutInput,
+  PartialLayoutLine,
+  WrapTextMeta,
+} from './types';
+
+export { applyOverflowFallback } from './fallback';
+

client/src/features/textWrap/overflow/types.ts

@@ -0,0 +1,47 @@
+import type { Token } from '../core/types';
+import type { ContextProfile, FontSpec, MeasureWidthImpl, TextWrapContext } from '../measure/types';
+
+export type OverflowMode = 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT';
+export type FallbackType = 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT';
+export type OverflowType = 'NONE' | 'ELLIPSIS' | 'CLIP';
+
+export type OverflowReason = 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'TOO_LONG' | 'WIDOW' | 'PARTICLE' | string;
+
+export type PartialLayoutLine = { start: number; end: number; text?: string };
+export type PartialLayoutInput = { breaks: number[]; lines: PartialLayoutLine[] };
+
+export type OverflowMeasure = {
+  context: TextWrapContext;
+  contextProfile: ContextProfile;
+  fontSpec: Partial<FontSpec> | null | undefined;
+  measureWidthImpl?: MeasureWidthImpl;
+  widgetEnableMeasure?: boolean;
+};
+
+export type ApplyOverflowFallbackInput = {
+  tokens: Token[];
+  lang: 'TC' | 'EN';
+  context: TextWrapContext;
+  availableWidth: number;
+  maxLines: number;
+  overflowMode: OverflowMode;
+  ellipsisToken: string;
+  reason: OverflowReason;
+  partialLayout?: PartialLayoutInput | null;
+  measure?: OverflowMeasure;
+  /** TC 标点集合（用于清理 `，…`） */
+  tcPunctuations?: string[];
+};
+
+export type WrapTextMeta = {
+  fallback_type: FallbackType;
+  overflow_type: OverflowType;
+  reason: OverflowReason;
+};
+
+export type ApplyOverflowFallbackResult = {
+  lines: string[];
+  wrappedText: string;
+  meta: WrapTextMeta;
+};
+

client/src/features/textWrap/scoring/__tests__/scoringTiebreak.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Token } from '../../core/types';
+import { buildTieKey, DEFAULT_LEXICONS, DEFAULT_WEIGHTS, scoreLayout } from '../index';
+
+function t(text: string, start: number): Token {
+  return { text, start, end: start + text.length };
+}
+
+function lexicographicLess(a: Array<number | string>, b: Array<number | string>): boolean {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const av = a[i] as any;
+    const bv = b[i] as any;
+    if (av < bv) return true;
+    if (av > bv) return false;
+  }
+  return a.length < b.length;
+}
+
+describe('textWrap scoring-tiebreak', () => {
+  it('EMOTION_SPLIT：拆分情绪短语 -> 强惩罚 + 追加 spanLen（方案 A）', () => {
+    const tokens: Token[] = [t('I', 0), t('am', 2), t('so', 5), t('tired', 8)];
+    const layoutCandidate = {
+      breaks: [3], // I am so | tired
+      lines: [
+        { start: 0, end: 3, text: 'I am so', width: 10, tokenCount: 3, charCount: 0 },
+        { start: 3, end: 4, text: 'tired', width: 10, tokenCount: 1, charCount: 0 },
+      ],
+    };
+
+    const res = scoreLayout({
+      tokens,
+      layoutCandidate,
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 100,
+      config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+      lexicons: { ...DEFAULT_LEXICONS, emotionPhrasesEN: ['so tired'] },
+      debug: true,
+    });
+
+    // 触发强惩罚：-(P_EMOTION_SPLIT + spanLen)
+    const first = res.scoreBreakdown?.terms[0];
+    expect(first?.key).toBe('EMOTION_SPLIT');
+    expect(first?.delta).toBe(-(DEFAULT_WEIGHTS.P_EMOTION_SPLIT + 2));
+    expect(res.flags.emotionSplit).toBe(true);
+  });
+
+  it('Shift/Accum/Self：EN 词两端带标点也应命中（全词等值匹配）', () => {
+    const tokens: Token[] = [t('but,', 0), t('still', 5), t('ok', 11)];
+    const layoutCandidate = {
+      breaks: [1], // but, | still ok
+      lines: [
+        // 把 width 设置到 idealWidth 上，避免 length 项干扰 debug Top-3
+        { start: 0, end: 1, text: 'but,', width: 90, tokenCount: 1, charCount: 0 },
+        { start: 1, end: 3, text: 'still ok', width: 90, tokenCount: 2, charCount: 0 },
+      ],
+    };
+
+    const res = scoreLayout({
+      tokens,
+      layoutCandidate,
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 100, // idealWidth=100*0.9=90
+      config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+      lexicons: DEFAULT_LEXICONS,
+      debug: true,
+    });
+
+    const terms = res.scoreBreakdown?.terms ?? [];
+    expect(terms.some((x) => x.key === 'SHIFT_BREAK')).toBe(true);
+    expect(terms.some((x) => x.key === 'ACCUM_BREAK')).toBe(true);
+  });
+
+  it('10.2G：EmotionWord 与 Accum 同时命中 -> Accum 奖励减半（整数）', () => {
+    const tokens: Token[] = [t('already', 0), t('tired', 8)];
+    const layoutCandidate = {
+      breaks: [1], // already | tired
+      lines: [
+        { start: 0, end: 1, text: 'already', width: 90, tokenCount: 1, charCount: 0 },
+        { start: 1, end: 2, text: 'tired', width: 90, tokenCount: 1, charCount: 0 },
+      ],
+    };
+
+    const weights = { ...DEFAULT_WEIGHTS, R_EMOTION_TAIL: 10, R_ACCUM_BREAK: 41 }; // 41/2 -> 20（floor）
+
+    const res = scoreLayout({
+      tokens,
+      layoutCandidate,
+      lang: 'EN',
+      context: 'APP',
+      availableWidth: 100,
+      config: { weights, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+      lexicons: DEFAULT_LEXICONS,
+      debug: true,
+    });
+
+    const terms = res.scoreBreakdown?.terms ?? [];
+    // debug 可能截断为 Top-3，但应包含 EMOTION_TAIL 与 ACCUM_BREAK（顺序确定性）
+    const hasEmotion = terms.some((x) => x.key === 'EMOTION_TAIL' && x.delta === 10);
+    const hasAccumHalf = terms.some((x) => x.key === 'ACCUM_BREAK' && x.delta === Math.floor(41 / 2));
+    expect(hasEmotion).toBe(true);
+    expect(hasAccumHalf).toBe(true);
+  });
+
+  it('tieKey：lastLineWidth 更大优先（取 -lastLineWidth）', () => {
+    const base = {
+      breaks: [2],
+      lines: [
+        { start: 0, end: 2, text: 'a b', width: 50, tokenCount: 2, charCount: 0 },
+        { start: 2, end: 3, text: 'c', width: 10, tokenCount: 1, charCount: 0 },
+      ],
+    };
+
+    const scoredA = { score: 0, flags: {}, tieKey: [] as any };
+    const scoredB = { score: 0, flags: {}, tieKey: [] as any };
+
+    const keyShort = buildTieKey({
+      scoredLayout: scoredA as any,
+      layoutCandidate: base as any,
+      lang: 'EN',
+      context: 'APP',
+      tokenCount: 3,
+      availableWidth: 100,
+      idealWidthRatio: { APP: 0.9, WIDGET: 0.95 },
+    });
+
+    const layoutLongTail = {
+      ...base,
+      lines: [
+        base.lines[0]!,
+        { ...base.lines[1]!, width: 30 }, // lastLineWidth 更大
+      ],
+    };
+    const keyLong = buildTieKey({
+      scoredLayout: scoredB as any,
+      layoutCandidate: layoutLongTail as any,
+      lang: 'EN',
+      context: 'APP',
+      tokenCount: 3,
+      availableWidth: 100,
+      idealWidthRatio: { APP: 0.9, WIDGET: 0.95 },
+    });
+
+    // 更优的 tieKey 应“更小”（因为 lastLineWidth 取负）
+    expect(lexicographicLess(keyLong, keyShort)).toBe(true);
+  });
+});
+

client/src/features/textWrap/scoring/index.ts

@@ -0,0 +1,21 @@
+export type {
+  LayoutCandidate,
+  LayoutCandidateLine,
+  Lexicons,
+  ScoredLayout,
+  ScoreBreakdown,
+  ScoreLayoutInput,
+  ScoreTerm,
+  ScoringConfig,
+  TextWrapContext,
+  Weights,
+} from './types';
+
+export { DEFAULT_LEXICONS, mergeLexicons } from './lexicons';
+export { DEFAULT_WEIGHTS, mergeWeights } from './weights';
+
+export { preparePhraseTokens, findPhraseSpans, isSpanSplitByBreaks } from './phraseMatch';
+export { scoreLayout } from './score';
+export type { BuildTieKeyInput } from './tieKey';
+export { buildTieKey } from './tieKey';
+

client/src/features/textWrap/scoring/lexicons.ts

@@ -0,0 +1,31 @@
+import type { Lexicons } from './types';
+
+/**
+ * scoring-tiebreak 最小词表（首版写死客户端）
+ *
+ * 来源：`设计说明文档/文档换行算法.md v1.2.1` 第 7 节
+ * 原则：少而准（后续通过打点迭代扩充）
+ */
+export const DEFAULT_LEXICONS: Readonly<Lexicons> = Object.freeze({
+  emotionPhrasesTC: [],
+  emotionPhrasesEN: [],
+  protectedPhrases: [],
+
+  shiftWordsTC: ['但', '可是', '然而', '却', '只是', '偏偏'],
+  shiftWordsEN: ['but', 'yet', 'so'],
+
+  accumWordsTC: ['已经', '一直', '曾经', '终于', '还是', '到现在'],
+  accumWordsEN: ['already', 'still', 'even', 'just', 'really'],
+
+  selfWordsTC: ['你', '我', '自己', '我们', '别人'],
+  selfWordsEN: ['you', 'yourself', 'me', 'we'],
+
+  emotionWordsTC: ['累', '痛', '怕', '孤单', '委屈', '撑', '崩溃', '放弃'],
+  emotionWordsEN: ['tired', 'afraid', 'lonely', 'hurt', 'overwhelmed', 'give up'],
+});
+
+export function mergeLexicons(overrides?: Partial<Lexicons> | null | undefined): Lexicons {
+  if (!overrides) return { ...DEFAULT_LEXICONS };
+  return { ...DEFAULT_LEXICONS, ...overrides };
+}
+

client/src/features/textWrap/scoring/phraseMatch.ts

@@ -0,0 +1,92 @@
+import type { Lang, Token } from '../core/types';
+import { matchENKeyword, normalizeENKeyword, normalizeWhitespace, tokenizeEN } from '../core/index';
+import { segmentGraphemes } from '../grapheme/index';
+
+export type PhraseSpan = { start: number; end: number; length: number };
+
+function toNonEmptyArray(parts: string[]): string[] {
+  return parts.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+export function preparePhraseTokens(phrase: string, lang: Lang): string[] {
+  const input = String(phrase ?? '');
+  if (input === '') return [];
+
+  if (lang === 'EN') {
+    const { normalizedText } = normalizeWhitespace(input, 'NORMALIZE');
+    const words = normalizedText.split(' ');
+    // EN：按“全词等值匹配”口径做归一化（小写 + 两端去常见标点）
+    return toNonEmptyArray(words).map((w) => normalizeENKeyword(w));
+  }
+
+  // TC：按 grapheme clusters
+  const { clusters } = segmentGraphemes(input, 'PREFERRED');
+  return clusters;
+}
+
+function tokenEqualsPhraseToken(tokenText: string, phraseToken: string, lang: Lang): boolean {
+  if (lang === 'EN') return matchENKeyword(tokenText, phraseToken);
+  return tokenText === phraseToken;
+}
+
+/**
+ * 在 tokens 中寻找 phraseTokens 的“连续区间完全匹配”（必须）。
+ *
+ * 输出顺序（确定性）：
+ * - start 升序
+ * - start 相同：length 降序（更长优先）
+ */
+export function findPhraseSpans(tokens: Token[], phraseTokens: string[], lang: Lang): PhraseSpan[] {
+  const n = tokens.length;
+  const m = phraseTokens.length;
+  if (n === 0 || m === 0 || m > n) return [];
+
+  const spans: PhraseSpan[] = [];
+
+  for (let i = 0; i <= n - m; i++) {
+    let ok = true;
+    for (let j = 0; j < m; j++) {
+      const t = tokens[i + j]?.text ?? '';
+      const p = phraseTokens[j] ?? '';
+      if (!tokenEqualsPhraseToken(t, p, lang)) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) spans.push({ start: i, end: i + m, length: m });
+  }
+
+  spans.sort((a, b) => {
+    if (a.start !== b.start) return a.start - b.start;
+    return b.length - a.length;
+  });
+  return spans;
+}
+
+/**
+ * 判断某个 span 是否被断点拆分到不同的行（即：span 内存在 break）。
+ *
+ * 说明：
+ * - span=[start,end) 是 token 索引区间
+ * - breaks[i] 是 token 边界索引（1..N-1）
+ * - 若存在 start < b < end，则 span 被拆分
+ */
+export function isSpanSplitByBreaks(span: PhraseSpan, breaks: number[]): boolean {
+  const s = span.start;
+  const e = span.end;
+  if (e - s <= 1) return false;
+  for (const b of breaks) {
+    if (b > s && b < e) return true;
+    if (b >= e) break; // breaks 升序：可提前退出
+  }
+  return false;
+}
+
+/**
+ * 仅用于测试：把 EN 文本按 core-contract 口径 tokenize。
+ */
+export function tokenizePhraseLikeInputEN(text: string): Token[] {
+  const { normalizedText } = normalizeWhitespace(text, 'NORMALIZE');
+  return tokenizeEN(normalizedText);
+}
+

client/src/features/textWrap/scoring/score.ts

@@ -0,0 +1,367 @@
+import type { Lang, Token } from '../core/types';
+import { normalizeENKeyword } from '../core/index';
+
+import type { LayoutCandidateLine, ScoreLayoutInput, ScoreTerm, ScoredLayout, Weights } from './types';
+import { findPhraseSpans, isSpanSplitByBreaks, preparePhraseTokens } from './phraseMatch';
+import { mergeLexicons } from './lexicons';
+import { mergeWeights } from './weights';
+
+function asInt(n: number): number {
+  // 保证输出整数（避免后续误用浮点）
+  return n | 0;
+}
+
+function absInt(n: number): number {
+  return n < 0 ? -n : n;
+}
+
+function roundToInt(n: number): number {
+  return Math.round(n);
+}
+
+function ratioToBp(ratio: number): number {
+  // 把 0.90 转为 900（bp=1/1000），用于尽量规避浮点带来的跨端差异
+  return Math.round(ratio * 1000);
+}
+
+function lineWidthOrApprox(line: LayoutCandidateLine, lang: Lang): number {
+  if (typeof line.width === 'number' && Number.isFinite(line.width)) return roundToInt(line.width);
+  // width unknown/approx：回退到 tokenCount / charCount（确定性）
+  return lang === 'EN' ? asInt(line.tokenCount) : asInt(line.charCount);
+}
+
+function buildSet(arr: string[] | undefined, lang: Lang): Set<string> {
+  if (!arr || arr.length === 0) return new Set();
+  if (lang === 'EN') return new Set(arr.map((w) => normalizeENKeyword(w)));
+  return new Set(arr);
+}
+
+function tokenHitSet(tokenText: string, set: Set<string>, lang: Lang): boolean {
+  if (set.size === 0) return false;
+  if (lang === 'EN') {
+    // 全词等值匹配（允许两端标点包裹）：normalize 后做等值命中即可
+    return set.has(normalizeENKeyword(tokenText));
+  }
+  return set.has(tokenText);
+}
+
+function isTcPunctuation(t: string, punctSet: Set<string>): boolean {
+  return punctSet.has(t);
+}
+
+function computeEmotionTailFlags(tokens: Token[], lines: LayoutCandidateLine[], lang: Lang, emotionWordsSet: Set<string>): boolean[] {
+  const flags: boolean[] = [];
+  if (emotionWordsSet.size === 0) return lines.map(() => false);
+
+  for (const line of lines) {
+    const start = Math.max(0, line.start | 0);
+    const end = Math.max(start, line.end | 0);
+    const slice = tokens.slice(start, end);
+
+    if (slice.length === 0) {
+      flags.push(false);
+      continue;
+    }
+
+    if (lang === 'EN') {
+      const last = slice[slice.length - 1]?.text ?? '';
+      flags.push(tokenHitSet(last, emotionWordsSet, 'EN'));
+      continue;
+    }
+
+    // TC：“最后 2 个 grapheme 范围内命中”
+    const last1 = slice[slice.length - 1]?.text ?? '';
+    const last2 = slice.length >= 2 ? slice[slice.length - 2]?.text ?? '' : '';
+    flags.push(tokenHitSet(last1, emotionWordsSet, 'TC') || tokenHitSet(last2, emotionWordsSet, 'TC'));
+  }
+
+  return flags;
+}
+
+function limitBreakdownForDebug(terms: ScoreTerm[]): ScoreTerm[] {
+  // 裁决补充 10.4A：debug Top-3 按规则优先级（10.1 顺序）输出
+  // 这里采用最稳妥的实现：直接取“按实现顺序生成的前 3 项”（确定性且满足优先级排序）
+  return terms.slice(0, 3);
+}
+
+export function scoreLayout(input: ScoreLayoutInput): ScoredLayout {
+  const weights: Weights = mergeWeights(input.config.weights);
+  const lexicons = mergeLexicons(input.lexicons);
+
+  const tokens = input.tokens ?? [];
+  const breaks = (input.layoutCandidate.breaks ?? []).slice().sort((a, b) => a - b);
+  const lines = input.layoutCandidate.lines ?? [];
+
+  const terms: ScoreTerm[] = [];
+  let score = 0;
+
+  const flags: ScoredLayout['flags'] = {
+    overflowed: Boolean(input.layoutCandidate.meta?.overflowed),
+    fallback: Boolean(input.layoutCandidate.meta?.fallback),
+  };
+
+  // ------------------------------
+  // 10.1-1 情绪短语拆分惩罚（最高优先）
+  // ------------------------------
+  {
+    let deltaEmotion = 0;
+    let deltaProtected = 0;
+
+    const listEmotion = input.lang === 'EN' ? lexicons.emotionPhrasesEN : lexicons.emotionPhrasesTC;
+    const listProtected = lexicons.protectedPhrases ?? [];
+
+    const pushSplit = (key: 'EMOTION_SPLIT' | 'PROTECTED_SPLIT', phrase: string, spanLen: number) => {
+      const base = key === 'EMOTION_SPLIT' ? weights.P_EMOTION_SPLIT : weights.P_PROTECTED_SPLIT;
+      const d = -asInt(base) - asInt(spanLen); // 方案 A：追加“被拆分短语长度”惩罚（更长短语更强保护）
+      if (key === 'EMOTION_SPLIT') deltaEmotion += d;
+      else deltaProtected += d;
+
+      flags.emotionSplit = true;
+      // 记录 detail 便于治理
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      terms.push({ key, delta: d, detail: { phrase, spanLen } });
+    };
+
+    // emotion phrases
+    for (const phrase of listEmotion) {
+      const phraseTokens = preparePhraseTokens(phrase, input.lang);
+      const spans = findPhraseSpans(tokens, phraseTokens, input.lang);
+      for (const span of spans) {
+        if (isSpanSplitByBreaks(span, breaks)) pushSplit('EMOTION_SPLIT', phrase, span.length);
+      }
+    }
+
+    // protected phrases
+    for (const phrase of listProtected) {
+      const phraseTokens = preparePhraseTokens(phrase, input.lang);
+      const spans = findPhraseSpans(tokens, phraseTokens, input.lang);
+      for (const span of spans) {
+        if (isSpanSplitByBreaks(span, breaks)) pushSplit('PROTECTED_SPLIT', phrase, span.length);
+      }
+    }
+
+    // 注意：这里已经把 term 推入了 terms（保持“优先级最高的项”最先出现）
+    score += deltaEmotion + deltaProtected;
+  }
+
+  // ------------------------------
+  // 10.1-2 行超长惩罚 + 理想长度奖励
+  // ------------------------------
+  {
+    const idealBp = ratioToBp(input.config.idealWidthRatio[input.context]);
+    const idealWidth = roundToInt((input.availableWidth * idealBp) / 1000);
+    const minPreferredRatio = input.config.minPreferredRatio ?? 0.6;
+    const minPreferredWidth = roundToInt((idealWidth * ratioToBp(minPreferredRatio)) / 1000);
+
+    let overMaxDelta = 0;
+    let idealDelta = 0;
+    let tooShortDelta = 0;
+
+    for (const line of lines) {
+      const w = lineWidthOrApprox(line, input.lang);
+
+      if (w > input.availableWidth) {
+        overMaxDelta -= asInt(weights.P_OVER_MAXLEN) * asInt(w - input.availableWidth);
+      }
+
+      idealDelta -= absInt(w - idealWidth);
+
+      if (w < minPreferredWidth) {
+        tooShortDelta -= asInt(weights.P_TOO_SHORT) * asInt(minPreferredWidth - w);
+      }
+    }
+
+    if (overMaxDelta !== 0) terms.push({ key: 'OVER_MAXLEN', delta: overMaxDelta, detail: { availableWidth: input.availableWidth } });
+    if (idealDelta !== 0) terms.push({ key: 'IDEAL_LEN', delta: idealDelta, detail: { idealWidth, idealBp } });
+    if (tooShortDelta !== 0) terms.push({ key: 'TOO_SHORT', delta: tooShortDelta, detail: { minPreferredWidth } });
+
+    score += overMaxDelta + idealDelta + tooShortDelta;
+  }
+
+  // ------------------------------
+  // 10.1-3 widow（EN）/ 单字行（TC）
+  // ------------------------------
+  {
+    const lastLine = lines[lines.length - 1];
+    if (lastLine) {
+      const lastWidth = lineWidthOrApprox(lastLine, input.lang);
+
+      if (input.lang === 'EN') {
+        const tokenCount = asInt(lastLine.tokenCount);
+        if (tokenCount === 1) {
+          const d = -asInt(weights.P_WIDOW_LINE);
+          terms.push({ key: 'WIDOW_LINE', delta: d });
+          score += d;
+
+          const start = Math.max(0, lastLine.start | 0);
+          const end = Math.max(start, lastLine.end | 0);
+          const only = tokens.slice(start, end)[0]?.text ?? '';
+          const norm = normalizeENKeyword(only);
+          const widowMaxLen = asInt(input.config.widowMaxLen ?? 3);
+          if (norm.length > 0 && norm.length <= widowMaxLen) {
+            const d2 = -asInt(weights.P_WIDOW_WORD);
+            terms.push({ key: 'WIDOW_WORD', delta: d2, detail: { word: norm, widowMaxLen } });
+            score += d2;
+          }
+        }
+      } else {
+        // TC：最后一行只有 1 个 grapheme（或 charCount<=1）视为“单字行”
+        const c = asInt(lastLine.charCount);
+        if (c <= 1) {
+          const d = -asInt(weights.P_WIDOW_LINE);
+          terms.push({ key: 'WIDOW_LINE', delta: d, detail: { tcSingleChar: true, lastWidth } });
+          score += d;
+        }
+      }
+    }
+  }
+
+  // ------------------------------
+  // 10.2F TC 助词孤立（在 10.1-3 后落地，保证顺序确定性）
+  // ------------------------------
+  if (input.lang === 'TC' && lines.length > 0) {
+    const particles = new Set(input.config.tcParticles ?? ['啊', '喔', '呢', '啦', '吗', '吧', '呀']);
+    const whitelist = new Set(input.config.tcParticleWhitelist ?? ['啊', '喔', '呢', '啦']);
+
+    let delta = 0;
+
+    for (const line of lines) {
+      const start = Math.max(0, line.start | 0);
+      const end = Math.max(start, line.end | 0);
+      const slice = tokens.slice(start, end);
+      if (slice.length === 0) continue;
+
+      const first = slice[0]?.text ?? '';
+      const last = slice[slice.length - 1]?.text ?? '';
+
+      const hitFirst = particles.has(first);
+      const hitLast = particles.has(last);
+      if (!hitFirst && !hitLast) continue;
+
+      const base = asInt(weights.P_PARTICLE_ISO);
+      const half = Math.floor(base / 2);
+
+      if (hitFirst) delta -= whitelist.has(first) ? half : base;
+      if (hitLast) delta -= whitelist.has(last) ? half : base;
+    }
+
+    if (delta !== 0) {
+      terms.push({ key: 'PARTICLE_ISO', delta, detail: { particles: Array.from(particles), whitelist: Array.from(whitelist) } });
+      score += delta;
+    }
+  }
+
+  // ------------------------------
+  // 10.1-4 标点断点奖励（TC）
+  // ------------------------------
+  if (input.lang === 'TC') {
+    const puncts = new Set(input.config.tcPunctuations ?? ['，', '。', '！', '？', '；', '：', '、']);
+    let delta = 0;
+
+    for (const b of breaks) {
+      const prev = tokens[b - 1]?.text ?? '';
+      if (isTcPunctuation(prev, puncts)) delta += asInt(weights.R_PUNCT_BREAK);
+    }
+
+    if (delta !== 0) {
+      terms.push({ key: 'PUNCT_BREAK', delta, detail: { tcPunctuations: Array.from(puncts) } });
+      score += delta;
+    }
+  }
+
+  // ------------------------------
+  // 10.1-5 Shift/Accum/Self 断点奖励（含 EN 行首/行尾感知）
+  // ------------------------------
+  {
+    const shiftSet = buildSet(input.lang === 'EN' ? lexicons.shiftWordsEN : lexicons.shiftWordsTC, input.lang);
+    const accumSet = buildSet(input.lang === 'EN' ? lexicons.accumWordsEN : lexicons.accumWordsTC, input.lang);
+    const selfSet = buildSet(input.lang === 'EN' ? lexicons.selfWordsEN : lexicons.selfWordsTC, input.lang);
+    const emotionSet = buildSet(input.lang === 'EN' ? lexicons.emotionWordsEN : lexicons.emotionWordsTC, input.lang);
+
+    const emotionTailByLine = computeEmotionTailFlags(tokens, lines, input.lang, emotionSet);
+
+    // EmotionWord 落点强化（默认权重为 0，不影响结果；但用于实现 10.2G 的“Accum 减半”规则）
+    let emotionTailDelta = 0;
+    for (let i = 0; i < emotionTailByLine.length; i++) {
+      if (emotionTailByLine[i]) emotionTailDelta += asInt(weights.R_EMOTION_TAIL);
+    }
+    if (emotionTailDelta !== 0) {
+      terms.push({ key: 'EMOTION_TAIL', delta: emotionTailDelta });
+      score += emotionTailDelta;
+    }
+
+    let shiftDelta = 0;
+    let accumDelta = 0;
+    let selfDelta = 0;
+
+    // 为 Accum 减半规则准备：把每个 break 映射到其左右行索引
+    // 假设 lines 与 breaks 一一对应：breaks[i] 分隔 lines[i] 与 lines[i+1]
+    for (let i = 0; i < breaks.length; i++) {
+      const b = breaks[i]!;
+      const prevLast = tokens[b - 1]?.text ?? '';
+      const nextFirst = tokens[b]?.text ?? '';
+
+      const hitShift = tokenHitSet(nextFirst, shiftSet, input.lang) || tokenHitSet(prevLast, shiftSet, input.lang);
+      const hitAccum = tokenHitSet(nextFirst, accumSet, input.lang) || tokenHitSet(prevLast, accumSet, input.lang);
+      const hitSelf = tokenHitSet(nextFirst, selfSet, input.lang) || tokenHitSet(prevLast, selfSet, input.lang);
+
+      if (hitShift) shiftDelta += asInt(weights.R_SHIFT_BREAK);
+      if (hitSelf) selfDelta += asInt(weights.R_SELF_BREAK);
+
+      if (hitAccum) {
+        // 10.2G：若同一行（或同一断点）同时满足 EmotionWord 强化与 Accum 奖励 -> Accum 减半
+        const leftLineIdx = i;
+        const rightLineIdx = i + 1;
+        const emotionHitNearby = Boolean(emotionTailByLine[leftLineIdx]) || Boolean(emotionTailByLine[rightLineIdx]);
+        const base = asInt(weights.R_ACCUM_BREAK);
+        const reward = emotionHitNearby ? Math.floor(base / 2) : base;
+        accumDelta += reward;
+      }
+    }
+
+    if (shiftDelta !== 0) {
+      terms.push({ key: 'SHIFT_BREAK', delta: shiftDelta });
+      score += shiftDelta;
+    }
+    if (accumDelta !== 0) {
+      terms.push({ key: 'ACCUM_BREAK', delta: accumDelta });
+      score += accumDelta;
+    }
+    if (selfDelta !== 0) {
+      terms.push({ key: 'SELF_BREAK', delta: selfDelta });
+      score += selfDelta;
+    }
+  }
+
+  // ------------------------------
+  // 10.1-6 多行视觉均衡（尾行过短惩罚）
+  // ------------------------------
+  {
+    const lastLine = lines[lines.length - 1];
+    if (lastLine) {
+      const idealBp = ratioToBp(input.config.idealWidthRatio[input.context]);
+      const idealWidth = roundToInt((input.availableWidth * idealBp) / 1000);
+      const shortRatio = input.config.shortLastLineRatio ?? 0.5;
+      const shortThreshold = roundToInt((idealWidth * ratioToBp(shortRatio)) / 1000);
+
+      const lastW = lineWidthOrApprox(lastLine, input.lang);
+      if (lastW < shortThreshold) {
+        const d = -asInt(weights.P_SHORT_LASTLINE);
+        terms.push({ key: 'SHORT_LASTLINE', delta: d, detail: { shortThreshold, lastW, idealWidth } });
+        score += d;
+      }
+    }
+  }
+
+  const scoreBreakdown = input.debug ? { total: score, terms: limitBreakdownForDebug(terms) } : undefined;
+
+  // tieKey 在 tieKey.ts 单独构造（此处返回占位，调用方可覆盖）
+  const tieKey: Array<number | string> = [
+    flags.emotionSplit ? 1 : 0,
+    flags.overflowed ? 1 : 0,
+    // lastLineWidth/spread/idealDistance 等由 buildTieKey 计算；这里仅保证结构存在
+  ];
+
+  return { score, flags, tieKey, scoreBreakdown };
+}
+

client/src/features/textWrap/scoring/tieKey.ts

@@ -0,0 +1,96 @@
+import type { Lang } from '../core/types';
+
+import type { LayoutCandidate, LayoutCandidateLine, ScoredLayout, TextWrapContext } from './types';
+
+function asInt(n: number): number {
+  return n | 0;
+}
+
+function roundToInt(n: number): number {
+  return Math.round(n);
+}
+
+function lineWidthOrApprox(line: LayoutCandidateLine, lang: Lang): number {
+  if (typeof line.width === 'number' && Number.isFinite(line.width)) return roundToInt(line.width);
+  return lang === 'EN' ? asInt(line.tokenCount) : asInt(line.charCount);
+}
+
+function computeIdealBreakPositions(nTokens: number, lineCount: number): number[] {
+  const n = Math.max(0, nTokens | 0);
+  const targetLines = Math.max(1, Math.min(lineCount | 0, n === 0 ? 1 : n));
+  const ideals: number[] = [];
+
+  for (let i = 1; i <= targetLines - 1; i++) {
+    ideals.push(Math.round((n * i) / targetLines));
+  }
+
+  ideals.sort((a, b) => a - b);
+  return ideals.filter((v, idx) => idx === 0 || v !== ideals[idx - 1]);
+}
+
+function sumAbs(a: number[], b: number[]): number {
+  const m = Math.min(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < m; i++) s += Math.abs((a[i] ?? 0) - (b[i] ?? 0));
+  // 若长度不等，用一个确定性惩罚补齐（避免 NaN，并让更“匹配理想结构”的更优）
+  if (a.length !== b.length) s += 100000 * Math.abs(a.length - b.length);
+  return s;
+}
+
+function computeSpread(widths: number[]): number {
+  if (widths.length === 0) return 0;
+  let min = widths[0]!;
+  let max = widths[0]!;
+  for (const w of widths) {
+    if (w < min) min = w;
+    if (w > max) max = w;
+  }
+  return max - min;
+}
+
+export type BuildTieKeyInput = {
+  scoredLayout: ScoredLayout;
+  layoutCandidate: LayoutCandidate;
+  lang: Lang;
+  context: TextWrapContext;
+  /** tokens.length（用于理想切分点距离；必须与 breaks/lines 的 token 体系一致） */
+  tokenCount: number;
+  /** 可用宽度（用于理想切分点/尾行宽度判断的辅助项；tieKey 主要使用 width 值） */
+  availableWidth: number;
+  idealWidthRatio: { APP: number; WIDGET: number };
+};
+
+/**
+ * 构造 tieKey（按文档 11 节顺序，必须确定性）：
+ * 1) emotionSplit=false 优先
+ * 2) overflowed=false 优先
+ * 3) lastLineWidth 更大优先
+ * 4) 行宽分布更均匀优先（max-min 更小）
+ * 5) 断点更接近理想切分点优先（距离之和更小）
+ * 6) breaks 字典序更靠前优先（在外部比较中按逐项数值比较即可）
+ */
+export function buildTieKey(args: BuildTieKeyInput): Array<number | string> {
+  const { scoredLayout, layoutCandidate } = args;
+  const lines = layoutCandidate.lines ?? [];
+  const breaks = (layoutCandidate.breaks ?? []).slice().sort((a, b) => a - b);
+
+  const widths = lines.map((l) => lineWidthOrApprox(l, args.lang));
+  const lastLineWidth = widths.length > 0 ? widths[widths.length - 1]! : 0;
+  const spread = computeSpread(widths);
+
+  const ideals = computeIdealBreakPositions(args.tokenCount, lines.length);
+  const idealDist = sumAbs(breaks, ideals);
+
+  const emotionSplitFlag = scoredLayout.flags.emotionSplit ? 1 : 0;
+  const overflowedFlag = scoredLayout.flags.overflowed ? 1 : 0;
+
+  return [
+    emotionSplitFlag,
+    overflowedFlag,
+    -lastLineWidth, // 更大优先 => 取负数实现“更小更优”
+    spread, // 更小更优
+    idealDist, // 更小更优
+    ...breaks,
+  ];
+}
+

client/src/features/textWrap/scoring/types.ts

@@ -0,0 +1,92 @@
+import type { Lang, Token } from '../core/types';
+
+export type TextWrapContext = 'APP' | 'WIDGET';
+
+export type LayoutCandidateLine = {
+  /**
+   * 该行对应的 token 区间（半开区间），单位与 `breaks` 一致：
+   * - start：包含
+   * - end：不包含
+   */
+  start: number;
+  end: number;
+  /** 该行展示文本（用于 debug；评分以 token/width 为主） */
+  text: string;
+  /**
+   * 该行宽度（同一候选集必须同一单位）。
+   * - App：像素等真实测量单位
+   * - Widget approx：可使用近似单位（例如 wordCount/graphemeCount）
+   */
+  width: number | null;
+  /** 该行 token 数（EN=词数；TC=grapheme 数） */
+  tokenCount: number;
+  /** 该行字符簇数（TC 使用；EN 可等于 tokenCount 或 0） */
+  charCount: number;
+};
+
+export type LayoutCandidate = {
+  /** 断点序列（token 边界索引），升序 */
+  breaks: number[];
+  /** 每行信息（lines.length = breaks.length + 1） */
+  lines: LayoutCandidateLine[];
+  /** 可选：外部模块（overflow/fallback）可透传的标记 */
+  meta?: { overflowed?: boolean; fallback?: boolean };
+};
+
+export type ScoreTerm = { key: string; delta: number; detail?: any };
+
+export type ScoreBreakdown = { total: number; terms: ScoreTerm[] };
+
+export type ScoredLayout = {
+  score: number;
+  flags: { emotionSplit?: boolean; overflowed?: boolean; fallback?: boolean };
+  tieKey: Array<number | string>;
+  scoreBreakdown?: ScoreBreakdown;
+};
+
+export type Weights = Record<string, number>;
+
+export type Lexicons = {
+  emotionPhrasesTC: string[];
+  emotionPhrasesEN: string[];
+  protectedPhrases?: string[];
+  shiftWordsTC: string[];
+  shiftWordsEN: string[];
+  accumWordsTC: string[];
+  accumWordsEN: string[];
+  selfWordsTC: string[];
+  selfWordsEN: string[];
+  emotionWordsTC?: string[];
+  emotionWordsEN?: string[];
+};
+
+export type ScoringConfig = {
+  weights: Weights;
+  idealWidthRatio: { APP: number; WIDGET: number };
+  ellipsisToken: string;
+  /** TC 标点集合（用于 PUNCT_BREAK 奖励与行首标点检测） */
+  tcPunctuations?: string[];
+  /** TC 助词集合（用于 PARTICLE_ISO） */
+  tcParticles?: string[];
+  /** TC 语尾语助词白名单：触发 PARTICLE_ISO 时惩罚减半 */
+  tcParticleWhitelist: string[];
+  /** Widow 短词阈值（EN）：len(word) <= widowMaxLen（默认 3） */
+  widowMaxLen?: number;
+  /** 过短阈值：minPreferred = idealWidth * minPreferredRatio（默认 0.6） */
+  minPreferredRatio?: number;
+  /** 尾行过短阈值：shortLastLine = idealWidth * shortLastLineRatio（默认 0.5） */
+  shortLastLineRatio?: number;
+};
+
+export type ScoreLayoutInput = {
+  tokens: Token[];
+  layoutCandidate: LayoutCandidate;
+  lang: Lang;
+  context: TextWrapContext;
+  /** 可用宽度（同 width 单位），必须由上游提供 */
+  availableWidth: number;
+  config: ScoringConfig;
+  lexicons: Lexicons;
+  debug?: boolean;
+};
+

client/src/features/textWrap/scoring/weights.ts

@@ -0,0 +1,35 @@
+import type { Weights } from './types';
+
+/**
+ * scoring-tiebreak 默认权重（首版写死客户端）
+ *
+ * 来源：`设计说明文档/文档换行算法.md v1.2.1` 10.3
+ */
+export const DEFAULT_WEIGHTS = Object.freeze({
+  P_EMOTION_SPLIT: 10000,
+  P_PROTECTED_SPLIT: 10000,
+  P_WIDOW_WORD: 800,
+  P_WIDOW_LINE: 500,
+  P_SHORT_LASTLINE: 300,
+  P_PARTICLE_ISO: 200,
+  R_PUNCT_BREAK: 80,
+  R_SHIFT_BREAK: 60,
+  R_ACCUM_BREAK: 40,
+  R_SELF_BREAK: 20,
+  P_OVER_MAXLEN: 30,
+  P_TOO_SHORT: 10,
+
+  /**
+   * 预留：情绪词落点强化（文档 7.2 / 10.2G 提到）
+   * - 为避免偏离 10.3 首版权重，本实现默认置 0（不影响结果）
+   * - 若后续需要启用，可通过 overrides 提供非 0 权重，并用 configVersion 管理
+   */
+  R_EMOTION_TAIL: 0,
+  P_EMOTION_BURIED: 0,
+} satisfies Weights);
+
+export function mergeWeights(overrides?: Partial<Weights> | null | undefined): Weights {
+  if (!overrides) return { ...DEFAULT_WEIGHTS };
+  return { ...DEFAULT_WEIGHTS, ...overrides };
+}
+

client/src/features/textWrap/searchApp/__tests__/searchApp.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeasureWidthImpl } from '../../measure/types';
+import { searchBestLayoutApp } from '../index';
+import { DEFAULT_LEXICONS, DEFAULT_WEIGHTS } from '../../scoring/index';
+
+function t(text: string, start: number) {
+  return { text, start, end: start + text.length };
+}
+
+describe('textWrap search-engine-app', () => {
+  it('确定性：同输入多次调用 breaks/lines 必须一致', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const input = {
+      tokens: [t('I', 0), t('am', 2), t('so', 5), t('tired', 8)],
+      lang: 'EN' as const,
+      breakpoints: [
+        { pos: 1, kind: 'SPACE', priority: 10 },
+        { pos: 2, kind: 'SPACE', priority: 10 },
+        { pos: 3, kind: 'SPACE', priority: 10 },
+      ],
+      availableWidth: 6,
+      maxLines: 2,
+      lineMode: 'AUTO' as const,
+      measure: {
+        contextProfile: 'APP|ios|test',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+      },
+      scoring: {
+        config: {
+          weights: DEFAULT_WEIGHTS,
+          idealWidthRatio: { APP: 0.9, WIDGET: 0.95 },
+          ellipsisToken: '…',
+          tcParticleWhitelist: [],
+        },
+        lexicons: DEFAULT_LEXICONS,
+        debug: true,
+      },
+    };
+
+    const a = await searchBestLayoutApp(input as any);
+    const b = await searchBestLayoutApp(input as any);
+    const c = await searchBestLayoutApp(input as any);
+
+    expect(a).toEqual(b);
+    expect(b).toEqual(c);
+    expect(impl).toHaveBeenCalled(); // 有测量发生
+  });
+
+  it('lineMode=FIXED：无解必须返回 NO_CANDIDATE', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const res = await searchBestLayoutApp({
+      tokens: [t('I', 0), t('am', 2)],
+      lang: 'EN',
+      breakpoints: [{ pos: 1, kind: 'SPACE', priority: 10 }],
+      availableWidth: 100,
+      maxLines: 3,
+      lineMode: 'FIXED',
+      measure: {
+        contextProfile: 'APP|ios|fixed',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+      },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+        lexicons: DEFAULT_LEXICONS,
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toBe('NO_CANDIDATE');
+  });
+
+  it('TC H6：断点导致下一行行首为标点时必须禁止', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const res = await searchBestLayoutApp({
+      tokens: [t('我', 0), t('好', 1), t('，', 2), t('累', 3)],
+      lang: 'TC',
+      // 若选择 pos=2，则第二行行首 token 为 '，'（应禁止）
+      breakpoints: [{ pos: 2, kind: 'PUNCT', priority: 30 }],
+      availableWidth: 100,
+      maxLines: 2,
+      lineMode: 'FIXED',
+      measure: {
+        contextProfile: 'APP|ios|tc',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+      },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [], tcPunctuations: ['，'] },
+        lexicons: DEFAULT_LEXICONS,
+      },
+    });
+
+    // lineMode=FIXED 且唯一断点被禁止，因此无解
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toBe('NO_CANDIDATE');
+  });
+
+  it('TOO_LONG：超过阈值直接返回 TOO_LONG', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const tokens = Array.from({ length: 31 }).map((_, i) => t('a', i));
+    const res = await searchBestLayoutApp({
+      tokens,
+      lang: 'EN',
+      breakpoints: [],
+      availableWidth: 100,
+      maxLines: 2,
+      lineMode: 'AUTO',
+      measure: {
+        contextProfile: 'APP|ios|toolong',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+      },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+        lexicons: DEFAULT_LEXICONS,
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toBe('TOO_LONG');
+  });
+});
+

client/src/features/textWrap/searchApp/constraints.ts

@@ -0,0 +1,21 @@
+import type { Token } from '../core/types';
+
+export const DEFAULT_TOO_LONG_THRESHOLDS = Object.freeze({ EN: 30, TC: 60 });
+
+export function isTooLong(tokens: Token[], lang: 'TC' | 'EN', thresholds: { EN: number; TC: number }): boolean {
+  const n = Math.max(0, tokens.length | 0);
+  const limit = lang === 'EN' ? thresholds.EN : thresholds.TC;
+  return n > limit;
+}
+
+export function isLineStartPunctTC(tokens: Token[], pos: number, tcPunctuations: string[]): boolean {
+  const p = pos | 0;
+  if (p <= 0) return false; // 第一行不受 H6 影响
+  const t = tokens[p]?.text ?? '';
+  return tcPunctuations.includes(t);
+}
+
+export function isOverWidth(width: number, availableWidth: number): boolean {
+  return width > availableWidth;
+}
+

client/src/features/textWrap/searchApp/dpTopK.ts

@@ -0,0 +1,221 @@
+import type { Token } from '../core/types';
+import type { Breakpoint } from '../breakpoints/types';
+
+import { joinTokens } from '../core/joinTokens';
+import { measureSliceWidthCached } from '../measure/measureSliceWidthCached';
+import { buildTieKey, scoreLayout } from '../scoring/index';
+
+import { DEFAULT_TOO_LONG_THRESHOLDS, isLineStartPunctTC, isOverWidth, isTooLong } from './constraints';
+import { insertTopK } from './topK';
+import type { BestLayout, PartialLayout, SearchAppConfig, SearchAppInput, SearchAppResult } from './types';
+
+const DEFAULT_CONFIG: SearchAppConfig = {
+  topK: 10,
+  tooLongThresholds: DEFAULT_TOO_LONG_THRESHOLDS,
+};
+
+function mergeConfig(overrides?: Partial<SearchAppConfig> | null): SearchAppConfig {
+  if (!overrides) return { ...DEFAULT_CONFIG };
+  return {
+    topK: overrides.topK ?? DEFAULT_CONFIG.topK,
+    tooLongThresholds: overrides.tooLongThresholds ?? DEFAULT_CONFIG.tooLongThresholds,
+  };
+}
+
+function uniqueSortedPositions(bps: Breakpoint[], n: number): number[] {
+  const set = new Set<number>();
+  for (const b of bps) {
+    const p = b.pos | 0;
+    if (p >= 1 && p <= n - 1) set.add(p);
+  }
+  const arr = Array.from(set);
+  arr.sort((a, b) => a - b);
+  return arr;
+}
+
+function rawSeparatorsForLang(tokensLen: number, lang: 'TC' | 'EN'): string[] | undefined {
+  if (lang !== 'TC') return undefined;
+  // TC：默认拼接不插入额外空格；空格作为 token 自身出现
+  return Array.from({ length: Math.max(0, tokensLen) }, () => '');
+}
+
+function buildLineText(tokens: Token[], start: number, end: number, rawSeparators?: string[]): string {
+  return joinTokens(tokens, start, end, rawSeparators);
+}
+
+function buildBestLayout(best: PartialLayout, debug?: boolean): BestLayout {
+  const lines = best.lines.map((l) => l.text);
+  const wrappedText = lines.join('\n');
+  const meta = debug
+    ? { breaks: best.breaks, scoreTopTerms: best.scoreTopTerms, score: best.score }
+    : { breaks: best.breaks };
+  return { breaks: best.breaks, lines, wrappedText, meta };
+}
+
+export async function searchBestLayoutApp(input: SearchAppInput): Promise<SearchAppResult> {
+  const cfg = mergeConfig(input.config ?? null);
+  const tokens = input.tokens ?? [];
+  const lang = input.lang;
+  const n = tokens.length;
+
+  if (isTooLong(tokens, lang, cfg.tooLongThresholds)) {
+    return { ok: false, reason: 'TOO_LONG', meta: { tokenCount: n } };
+  }
+
+  const maxLines = Math.max(1, input.maxLines | 0);
+  const availableWidth = input.availableWidth;
+
+  const positions = uniqueSortedPositions(input.breakpoints ?? [], n);
+  const rawSep = rawSeparatorsForLang(tokens.length, lang);
+
+  // dp[pos][linesUsed] -> PartialLayout[]
+  const dp: PartialLayout[][][] = Array.from({ length: n + 1 }, () =>
+    Array.from({ length: maxLines + 1 }, () => [])
+  );
+
+  dp[0][0] = [
+    {
+      pos: 0,
+      breaks: [],
+      lines: [],
+      score: 0,
+      tieKey: [0, 0, 0, 0, 0], // 空布局占位，后续会用 buildTieKey 覆盖
+    },
+  ];
+
+  const tcPunctuations = input.scoring.config.tcPunctuations ?? ['，', '。', '！', '？', '；', '：', '、'];
+
+  // DP 遍历顺序必须固定
+  for (let pos = 0; pos <= n; pos++) {
+    for (let linesUsed = 0; linesUsed <= maxLines - 1; linesUsed++) {
+      const states = dp[pos][linesUsed];
+      if (!states || states.length === 0) continue;
+
+      // 枚举 nextPos：breakpoints 中 >pos 的位置（升序）+ N
+      const nextList: number[] = [];
+      for (const p of positions) if (p > pos) nextList.push(p);
+      if (n > pos) nextList.push(n);
+
+      for (const state of states) {
+        for (const nextPos of nextList) {
+          if (nextPos <= pos) continue; // 禁止空行
+
+          // H6：TC 禁止“行首标点”（断点导致下一行第一个 token 为标点）
+          // 断点位置为 nextPos，因此要检查 tokens[nextPos]
+          if (lang === 'TC' && nextPos < n && isLineStartPunctTC(tokens, nextPos, tcPunctuations)) {
+            continue;
+          }
+
+          const lineText = buildLineText(tokens, pos, nextPos, rawSep);
+
+          const widthRes = await measureSliceWidthCached({
+            tokens,
+            start: pos,
+            end: nextPos,
+            context: 'APP',
+            contextProfile: input.measure.contextProfile,
+            fontSpec: input.measure.fontSpec,
+            measureWidthImpl: input.measure.measureWidthImpl,
+            rawSeparators: rawSep,
+          });
+
+          if (widthRes.width === null) {
+            // App 搜索必须依赖宽度派；宽度不可用交给 overflow-fallback 统一处理
+            return {
+              ok: false,
+              reason: widthRes.meta.reason === 'MEASURE_FAILED' ? 'MEASURE_FAILED' : 'WIDTH_UNKNOWN',
+              meta: { tokenCount: n },
+            };
+          }
+
+          const lineWidth = widthRes.width;
+          if (isOverWidth(lineWidth, availableWidth)) continue; // H1
+
+          const tokenCount = nextPos - pos;
+          const charCount = lang === 'TC' ? tokenCount : 0;
+
+          const newLine = {
+            start: pos,
+            end: nextPos,
+            text: lineText,
+            width: lineWidth,
+            tokenCount,
+            charCount,
+          };
+
+          const newLines = state.lines.concat([newLine]);
+          const newBreaks = nextPos === n ? state.breaks : state.breaks.concat([nextPos]);
+
+          // 构造 layoutCandidate 并评分（为保证确定性，首版直接全量评分）
+          const layoutCandidate = { breaks: newBreaks, lines: newLines };
+
+          const scored = scoreLayout({
+            tokens,
+            layoutCandidate: layoutCandidate as any,
+            lang,
+            context: 'APP',
+            availableWidth,
+            config: input.scoring.config,
+            lexicons: input.scoring.lexicons,
+            debug: Boolean(input.scoring.debug),
+          });
+
+          const tieKey = buildTieKey({
+            scoredLayout: scored as any,
+            layoutCandidate: layoutCandidate as any,
+            lang,
+            context: 'APP',
+            tokenCount: n,
+            availableWidth,
+            idealWidthRatio: input.scoring.config.idealWidthRatio,
+          }) as number[];
+
+          const cand: PartialLayout = {
+            pos: nextPos,
+            breaks: newBreaks,
+            lines: newLines,
+            score: scored.score,
+            tieKey,
+            scoreTopTerms: scored.scoreBreakdown?.terms,
+          };
+
+          dp[nextPos][linesUsed + 1] = insertTopK(dp[nextPos][linesUsed + 1], cand, cfg.topK);
+        }
+      }
+    }
+  }
+
+  // 结束选择
+  const collect: PartialLayout[] = [];
+  if (input.lineMode === 'FIXED') {
+    collect.push(...dp[n][maxLines]);
+  } else {
+    for (let linesUsed = 1; linesUsed <= maxLines; linesUsed++) {
+      collect.push(...dp[n][linesUsed]);
+    }
+  }
+
+  if (collect.length === 0) {
+    return { ok: false, reason: 'NO_CANDIDATE', meta: { tokenCount: n } };
+  }
+
+  // TopK 容器内本身已排序，但跨不同 linesUsed 需要再全局选最优
+  collect.sort((a, b) => {
+    // 复用 insertTopK 的 compare 规则（在 topK.ts 内部）会更好，但这里直接再排序一次确保稳定
+    if (a.score !== b.score) return b.score - a.score;
+    const na = a.tieKey;
+    const nb = b.tieKey;
+    const m = Math.min(na.length, nb.length);
+    for (let i = 0; i < m; i++) {
+      const av = na[i] ?? 0;
+      const bv = nb[i] ?? 0;
+      if (av < bv) return -1;
+      if (av > bv) return 1;
+    }
+    return na.length - nb.length;
+  });
+
+  const best = collect[0]!;
+  return { ok: true, bestLayout: buildBestLayout(best, Boolean(input.scoring.debug)) };
+}
+

client/src/features/textWrap/searchApp/index.ts

@@ -0,0 +1,4 @@
+export type { BestLayout, LineMode, SearchAppConfig, SearchAppInput, SearchAppResult, SearchFailureReason } from './types';
+
+export { searchBestLayoutApp } from './dpTopK';
+

client/src/features/textWrap/searchApp/topK.ts

@@ -0,0 +1,62 @@
+import type { PartialLayout } from './types';
+import { compareBreaksLexicographically } from '../core/index';
+
+function compareTieKey(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  if (a.length < b.length) return -1;
+  if (a.length > b.length) return 1;
+  return 0;
+}
+
+/**
+ * TopK 排序（确定性）：
+ * - score 越大越优
+ * - tieKey 越小越优（按 11 节构造的数值 key）
+ * - breaks 字典序更小者更优（11.0A）
+ */
+export function compareLayouts(a: PartialLayout, b: PartialLayout): number {
+  if (a.score !== b.score) return b.score - a.score;
+  const t = compareTieKey(a.tieKey, b.tieKey);
+  if (t !== 0) return t;
+  return compareBreaksLexicographically(a.breaks, b.breaks);
+}
+
+function breaksKey(breaks: number[]): string {
+  // breaks 序列作为去重 key（确定性）
+  return breaks.join(',');
+}
+
+/**
+ * 插入 TopK（去重 + 排序 + 截断）。
+ *
+ * 去重规则：
+ * - 同 breaks 仅保留最优（score 更高；若相同按 tieKey/breaks 比较）
+ */
+export function insertTopK(list: PartialLayout[], cand: PartialLayout, k: number): PartialLayout[] {
+  const K = Math.max(1, k | 0);
+  const out = list.slice();
+
+  const key = breaksKey(cand.breaks);
+  const idx = out.findIndex((x) => breaksKey(x.breaks) === key);
+  if (idx >= 0) {
+    const existing = out[idx]!;
+    if (compareLayouts(cand, existing) < 0) {
+      // cand 更差，忽略
+      return out;
+    }
+    out[idx] = cand;
+  } else {
+    out.push(cand);
+  }
+
+  out.sort(compareLayouts);
+  if (out.length > K) out.length = K;
+  return out;
+}
+

client/src/features/textWrap/searchApp/types.ts

@@ -0,0 +1,71 @@
+import type { Token } from '../core/types';
+import type { Breakpoint } from '../breakpoints/types';
+import type { ContextProfile, FontSpec, MeasureWidthImpl } from '../measure/types';
+import type { Lexicons, ScoringConfig, ScoreTerm } from '../scoring/types';
+
+export type LineMode = 'AUTO' | 'FIXED';
+
+export type SearchAppConfig = {
+  /** TopK（文档建议 App=10） */
+  topK: number;
+  /** 超长阈值（用于 TOO_LONG） */
+  tooLongThresholds: { EN: number; TC: number };
+};
+
+export type SearchMeasureInput = {
+  contextProfile: ContextProfile;
+  fontSpec: Partial<FontSpec> | null | undefined;
+  measureWidthImpl?: MeasureWidthImpl;
+};
+
+export type SearchScoringInput = {
+  config: ScoringConfig;
+  lexicons: Lexicons;
+  debug?: boolean;
+};
+
+export type SearchAppInput = {
+  tokens: Token[];
+  lang: 'TC' | 'EN';
+  breakpoints: Breakpoint[];
+  availableWidth: number;
+  maxLines: number;
+  lineMode: LineMode;
+  measure: SearchMeasureInput;
+  scoring: SearchScoringInput;
+  config?: Partial<SearchAppConfig>;
+};
+
+export type BestLayout = {
+  breaks: number[];
+  lines: string[];
+  wrappedText: string;
+  meta?: {
+    breaks: number[];
+    scoreTopTerms?: ScoreTerm[];
+    score?: number;
+  };
+};
+
+export type SearchFailureReason = 'TOO_LONG' | 'WIDTH_UNKNOWN' | 'MEASURE_FAILED' | 'NO_CANDIDATE';
+
+export type SearchAppResult =
+  | { ok: true; bestLayout: BestLayout }
+  | { ok: false; reason: SearchFailureReason; meta?: { tokenCount: number } };
+
+export type PartialLayout = {
+  pos: number;
+  breaks: number[];
+  lines: Array<{
+    start: number;
+    end: number;
+    text: string;
+    width: number;
+    tokenCount: number;
+    charCount: number;
+  }>;
+  score: number;
+  tieKey: number[];
+  scoreTopTerms?: ScoreTerm[];
+};
+

client/src/features/textWrap/searchWidget/__tests__/searchWidget.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeasureWidthImpl } from '../../measure/types';
+import { DEFAULT_LEXICONS, DEFAULT_WEIGHTS } from '../../scoring/index';
+import { searchBestLayoutWidget } from '../index';
+
+function t(text: string, start: number) {
+  return { text, start, end: start + text.length };
+}
+
+describe('textWrap search-engine-widget', () => {
+  it('确定性：同输入多次调用 breaks/lines 必须一致', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const input = {
+      tokens: [t('I', 0), t('am', 2), t('so', 5), t('tired', 8)],
+      lang: 'EN' as const,
+      breakpoints: [
+        { pos: 1, kind: 'SPACE', priority: 10 },
+        { pos: 2, kind: 'SPACE', priority: 10 },
+        { pos: 3, kind: 'SPACE', priority: 10 },
+      ],
+      availableWidth: 6,
+      maxLines: 2,
+      context: 'WIDGET' as const,
+      measure: {
+        widthMode: 'MEASURE' as const,
+        contextProfile: 'WIDGET|small|test',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+        widgetEnableMeasure: true,
+      },
+      scoring: {
+        config: {
+          weights: DEFAULT_WEIGHTS,
+          idealWidthRatio: { APP: 0.9, WIDGET: 0.95 },
+          ellipsisToken: '…',
+          tcParticleWhitelist: [],
+        },
+        lexicons: DEFAULT_LEXICONS,
+        debug: true,
+      },
+      config: { beamK: 5, expandM: 12 },
+    };
+
+    const a = await searchBestLayoutWidget(input as any);
+    const b = await searchBestLayoutWidget(input as any);
+    const c = await searchBestLayoutWidget(input as any);
+
+    expect(a).toEqual(b);
+    expect(b).toEqual(c);
+  });
+
+  it('widthMode=APPROX：仍可输出，并标记 meta.reason=WIDTH_UNKNOWN', async () => {
+    const res = await searchBestLayoutWidget({
+      tokens: [t('我', 0), t('好', 1), t('累', 2)],
+      lang: 'TC',
+      breakpoints: [{ pos: 1, kind: 'BALANCE', priority: 5 }],
+      // APPROX 模式下：availableWidth 与 width 单位都按“token 数”理解
+      availableWidth: 10,
+      maxLines: 2,
+      context: 'WIDGET',
+      measure: { widthMode: 'APPROX' },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+        lexicons: DEFAULT_LEXICONS,
+        debug: true,
+      },
+      config: { beamK: 3, expandM: 2 },
+    });
+
+    expect(res.ok).toBe(true);
+    if (res.ok) {
+      expect(res.bestLayout.meta?.reason).toBe('WIDTH_UNKNOWN');
+    }
+  });
+
+  it('性能约束：expandM/beamK 生效（通过测量调用次数粗略验证）', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const res = await searchBestLayoutWidget({
+      tokens: [t('a', 0), t('b', 2), t('c', 4), t('d', 6), t('e', 8)],
+      lang: 'EN',
+      breakpoints: [
+        { pos: 1, kind: 'SPACE', priority: 10 },
+        { pos: 2, kind: 'SPACE', priority: 10 },
+        { pos: 3, kind: 'SPACE', priority: 10 },
+        { pos: 4, kind: 'SPACE', priority: 10 },
+      ],
+      availableWidth: 100,
+      maxLines: 3,
+      context: 'WIDGET',
+      measure: {
+        widthMode: 'MEASURE',
+        contextProfile: 'WIDGET|perf',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+        widgetEnableMeasure: true,
+      },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [] },
+        lexicons: DEFAULT_LEXICONS,
+      },
+      config: { beamK: 2, expandM: 2 },
+    });
+
+    expect(res.ok).toBe(true);
+    // 每轮最多 beamK 个 beam，每个 beam 最多 expandM 次扩展 -> 粗略上限：maxLines*beamK*expandM
+    expect((impl as any).mock.calls.length).toBeLessThanOrEqual(3 * 2 * 2 + 2);
+  });
+
+  it('TC H6：行首标点导致的转移必须被禁止', async () => {
+    const impl: MeasureWidthImpl = vi.fn(async ({ text }) => text.length);
+    const res = await searchBestLayoutWidget({
+      tokens: [t('我', 0), t('好', 1), t('，', 2), t('累', 3)],
+      lang: 'TC',
+      breakpoints: [{ pos: 2, kind: 'PUNCT', priority: 30 }],
+      // 让“一行放下全文”不可能（触发超宽过滤），从而必须依赖断点切分
+      availableWidth: 3,
+      maxLines: 2,
+      context: 'WIDGET',
+      measure: {
+        widthMode: 'MEASURE',
+        contextProfile: 'WIDGET|tc',
+        fontSpec: { fontFamily: 'PingFangSC-Regular', fontWeight: '400', fontSize: 16 },
+        measureWidthImpl: impl,
+        widgetEnableMeasure: true,
+      },
+      scoring: {
+        config: { weights: DEFAULT_WEIGHTS, idealWidthRatio: { APP: 0.9, WIDGET: 0.95 }, ellipsisToken: '…', tcParticleWhitelist: [], tcPunctuations: ['，'] },
+        lexicons: DEFAULT_LEXICONS,
+      },
+      config: { beamK: 3, expandM: 3 },
+    });
+
+    expect(res.ok).toBe(false);
+    if (!res.ok) expect(res.reason).toBe('NO_CANDIDATE');
+  });
+});
+

client/src/features/textWrap/searchWidget/beam.ts

@@ -0,0 +1,263 @@
+import type { Token } from '../core/types';
+import type { Breakpoint } from '../breakpoints/types';
+
+import { joinTokens } from '../core/joinTokens';
+import { measureSliceWidthCached } from '../measure/measureSliceWidthCached';
+import { buildTieKey, scoreLayout } from '../scoring/index';
+
+import { approxWidth, DEFAULT_TOO_LONG_THRESHOLDS, isLineStartPunctTC, isTooLong } from './constraints';
+import { insertBeamTopK } from './topK';
+import type { BestWidgetLayout, SearchWidgetConfig, SearchWidgetInput, SearchWidgetResult, WidgetBeam } from './types';
+
+const DEFAULT_CONFIG: SearchWidgetConfig = {
+  beamK: 5,
+  expandM: 12,
+  tooLongThresholds: DEFAULT_TOO_LONG_THRESHOLDS,
+};
+
+function mergeConfig(overrides?: Partial<SearchWidgetConfig> | null): SearchWidgetConfig {
+  if (!overrides) return { ...DEFAULT_CONFIG };
+  return {
+    beamK: overrides.beamK ?? DEFAULT_CONFIG.beamK,
+    expandM: overrides.expandM ?? DEFAULT_CONFIG.expandM,
+    tooLongThresholds: overrides.tooLongThresholds ?? DEFAULT_CONFIG.tooLongThresholds,
+  };
+}
+
+function uniqueSortedPositions(bps: Breakpoint[], n: number): number[] {
+  const set = new Set<number>();
+  for (const b of bps) {
+    const p = b.pos | 0;
+    if (p >= 1 && p <= n - 1) set.add(p);
+  }
+  const arr = Array.from(set);
+  arr.sort((a, b) => a - b);
+  return arr;
+}
+
+function rawSeparatorsForLang(tokensLen: number, lang: 'TC' | 'EN'): string[] | undefined {
+  if (lang !== 'TC') return undefined;
+  // TC：默认拼接不插入额外空格；空格 token 自己决定展示
+  return Array.from({ length: Math.max(0, tokensLen) }, () => '');
+}
+
+function buildLineText(tokens: Token[], start: number, end: number, rawSeparators?: string[]): string {
+  return joinTokens(tokens, start, end, rawSeparators);
+}
+
+function mergeApproxReason(a?: 'WIDTH_UNKNOWN' | 'MEASURE_FAILED', b?: 'WIDTH_UNKNOWN' | 'MEASURE_FAILED') {
+  if (a === 'MEASURE_FAILED' || b === 'MEASURE_FAILED') return 'MEASURE_FAILED';
+  if (a === 'WIDTH_UNKNOWN' || b === 'WIDTH_UNKNOWN') return 'WIDTH_UNKNOWN';
+  return undefined;
+}
+
+function buildBestLayout(best: WidgetBeam, debug?: boolean): BestWidgetLayout {
+  const lines = best.lines.map((l) => l.text);
+  const wrappedText = lines.join('\n');
+
+  const reason = best.lines.reduce<'WIDTH_UNKNOWN' | 'MEASURE_FAILED' | undefined>((acc, l) => {
+    return mergeApproxReason(acc, l.approxReason);
+  }, undefined);
+
+  const meta = debug
+    ? { breaks: best.breaks, scoreTopTerms: best.scoreTopTerms, score: best.score, reason }
+    : { breaks: best.breaks, reason };
+
+  return { breaks: best.breaks, lines, wrappedText, meta };
+}
+
+export async function searchBestLayoutWidget(input: SearchWidgetInput): Promise<SearchWidgetResult> {
+  const cfg = mergeConfig(input.config ?? null);
+  const tokens = input.tokens ?? [];
+  const lang = input.lang;
+  const n = tokens.length;
+
+  if (isTooLong(tokens, lang, cfg.tooLongThresholds)) {
+    return { ok: false, reason: 'TOO_LONG', meta: { tokenCount: n } };
+  }
+
+  const maxLines = Math.max(1, input.maxLines | 0);
+  const availableWidth = input.availableWidth;
+
+  const positions = uniqueSortedPositions(input.breakpoints ?? [], n);
+  const rawSep = rawSeparatorsForLang(tokens.length, lang);
+
+  const tcPunctuations = input.scoring.config.tcPunctuations ?? ['，', '。', '！', '？', '；', '：', '、'];
+
+  // 初始 beams
+  let beams: WidgetBeam[] = [
+    { pos: 0, breaks: [], lines: [], score: 0, tieKey: [0, 0, 0, 0, 0] },
+  ];
+
+  for (let lineIndex = 1; lineIndex <= maxLines; lineIndex++) {
+    let newBeams: WidgetBeam[] = [];
+
+    // 关键：保留已完成（pos==N）的 beams，避免“提前完成的解”在后续轮次被丢弃
+    // 否则会错误地倾向“凑满 maxLines 行”的解，造成断句很怪（例如把“村莊”拆开）
+    for (const b of beams) {
+      if (b.pos === n) {
+        newBeams = insertBeamTopK(newBeams, b, cfg.beamK);
+      }
+    }
+
+    // beams 顺序固定：按当前排序后的顺序扩展
+    //（insertBeamTopK 会保持排序；这里再 sort 一次防御）
+    beams = beams.slice().sort((a, b) => {
+      if (a.score !== b.score) return b.score - a.score;
+      const na = a.tieKey;
+      const nb = b.tieKey;
+      const m = Math.min(na.length, nb.length);
+      for (let i = 0; i < m; i++) {
+        const av = na[i] ?? 0;
+        const bv = nb[i] ?? 0;
+        if (av < bv) return -1;
+        if (av > bv) return 1;
+      }
+      return na.length - nb.length;
+    });
+
+    for (const beam of beams) {
+      const pos = beam.pos;
+      if (pos >= n) continue;
+
+      // nextPos：pos 升序 + N
+      const nextList: number[] = [];
+      for (const p of positions) if (p > pos) nextList.push(p);
+      if (n > pos) nextList.push(n);
+
+      // expandM 裁剪：只取前 M 个（确定性：按 pos 升序），但必须保证 N（结束边界）始终可选
+      // 否则会出现“明明一行就能结束，却被裁剪掉只能继续拆分”的怪异换行。
+      const M = Math.max(1, cfg.expandM | 0);
+      let trimmed: number[];
+      if (M === 1) {
+        trimmed = [n];
+      } else {
+        const withoutN = nextList.filter((x) => x !== n);
+        trimmed = withoutN.slice(0, M - 1);
+        trimmed.push(n);
+      }
+
+      for (const nextPos of trimmed) {
+        if (nextPos <= pos) continue; // 禁止空行
+
+        // H6：TC 禁止行首标点（断点导致下一行第一个 token 为标点）
+        if (lang === 'TC' && nextPos < n && isLineStartPunctTC(tokens, nextPos, tcPunctuations)) {
+          continue;
+        }
+
+        const tokenCount = nextPos - pos;
+        const charCount = lang === 'TC' ? tokenCount : 0;
+        const lineText = buildLineText(tokens, pos, nextPos, rawSep);
+
+        let lineWidth: number;
+        let isApprox = false;
+        let approxReason: 'WIDTH_UNKNOWN' | 'MEASURE_FAILED' | undefined;
+        let widthTrusted = false;
+
+        if (input.measure.widthMode === 'APPROX') {
+          isApprox = true;
+          approxReason = 'WIDTH_UNKNOWN';
+          lineWidth = approxWidth(tokenCount, charCount, lang);
+        } else {
+          const widgetEnableMeasure = input.measure.widgetEnableMeasure ?? true;
+          const res = await measureSliceWidthCached({
+            tokens,
+            start: pos,
+            end: nextPos,
+            context: 'WIDGET',
+            contextProfile: input.measure.contextProfile,
+            fontSpec: input.measure.fontSpec,
+            measureWidthImpl: input.measure.measureWidthImpl,
+            widgetEnableMeasure,
+            rawSeparators: rawSep,
+          });
+
+          if (res.width === null) {
+            isApprox = true;
+            approxReason = res.meta.reason ?? 'WIDTH_UNKNOWN';
+            lineWidth = approxWidth(tokenCount, charCount, lang);
+          } else {
+            widthTrusted = true;
+            lineWidth = res.width;
+          }
+        }
+
+        // 超宽过滤：仅当宽度可信时执行
+        if (widthTrusted && lineWidth > availableWidth) continue;
+
+        const newLine = {
+          start: pos,
+          end: nextPos,
+          text: lineText,
+          width: lineWidth,
+          tokenCount,
+          charCount,
+          isApprox,
+          approxReason,
+        };
+
+        const newLines = beam.lines.concat([newLine]);
+        const newBreaks = nextPos === n ? beam.breaks : beam.breaks.concat([nextPos]);
+        const layoutCandidate = { breaks: newBreaks, lines: newLines.map(({ isApprox: _a, approxReason: _b, ...rest }) => rest) };
+
+        const scored = scoreLayout({
+          tokens,
+          layoutCandidate: layoutCandidate as any,
+          lang,
+          context: 'WIDGET',
+          availableWidth,
+          config: input.scoring.config,
+          lexicons: input.scoring.lexicons,
+          debug: Boolean(input.scoring.debug),
+        });
+
+        const tieKey = buildTieKey({
+          scoredLayout: scored as any,
+          layoutCandidate: layoutCandidate as any,
+          lang,
+          context: 'WIDGET',
+          tokenCount: n,
+          availableWidth,
+          idealWidthRatio: input.scoring.config.idealWidthRatio,
+        }) as number[];
+
+        const cand: WidgetBeam = {
+          pos: nextPos,
+          breaks: newBreaks,
+          lines: newLines,
+          score: scored.score,
+          tieKey,
+          scoreTopTerms: scored.scoreBreakdown?.terms,
+        };
+
+        newBeams = insertBeamTopK(newBeams, cand, cfg.beamK);
+      }
+    }
+
+    beams = newBeams;
+    if (beams.length === 0) break;
+  }
+
+  const finished = beams.filter((b) => b.pos === n);
+  if (finished.length === 0) {
+    return { ok: false, reason: 'NO_CANDIDATE', meta: { tokenCount: n } };
+  }
+
+  finished.sort((a, b) => {
+    if (a.score !== b.score) return b.score - a.score;
+    const na = a.tieKey;
+    const nb = b.tieKey;
+    const m = Math.min(na.length, nb.length);
+    for (let i = 0; i < m; i++) {
+      const av = na[i] ?? 0;
+      const bv = nb[i] ?? 0;
+      if (av < bv) return -1;
+      if (av > bv) return 1;
+    }
+    return na.length - nb.length;
+  });
+
+  const best = finished[0]!;
+  return { ok: true, bestLayout: buildBestLayout(best, Boolean(input.scoring.debug)) };
+}
+

client/src/features/textWrap/searchWidget/constraints.ts

@@ -0,0 +1,21 @@
+import type { Token } from '../core/types';
+
+export const DEFAULT_TOO_LONG_THRESHOLDS = Object.freeze({ EN: 30, TC: 60 });
+
+export function isTooLong(tokens: Token[], lang: 'TC' | 'EN', thresholds: { EN: number; TC: number }): boolean {
+  const n = Math.max(0, tokens.length | 0);
+  const limit = lang === 'EN' ? thresholds.EN : thresholds.TC;
+  return n > limit;
+}
+
+export function isLineStartPunctTC(tokens: Token[], nextPos: number, tcPunctuations: string[]): boolean {
+  const p = nextPos | 0;
+  if (p <= 0) return false;
+  const t = tokens[p]?.text ?? '';
+  return tcPunctuations.includes(t);
+}
+
+export function approxWidth(tokenCount: number, charCount: number, lang: 'TC' | 'EN'): number {
+  return lang === 'EN' ? tokenCount : charCount;
+}
+

client/src/features/textWrap/searchWidget/index.ts

@@ -0,0 +1,13 @@
+export type {
+  BestWidgetLayout,
+  SearchWidgetConfig,
+  SearchWidgetFailureReason,
+  SearchWidgetInput,
+  SearchWidgetMeasureInput,
+  SearchWidgetResult,
+  WidthMode,
+  WidgetBeam,
+} from './types';
+
+export { searchBestLayoutWidget } from './beam';
+