@tbox.cn/app-template-agent 0.7.5 → 0.8.0

package/packages/agent-ui-kit/src/theme/contract.json

@@ -0,0 +1,72 @@
+{
+  "$comment": "主题可覆写变量封闭清单（主题轨 W-T2；doctor theme-package-structure 消费——超集即 error；theme-contract.test.ts 锁 tokens.less+motion.less 的平台键 ⊆ platform 段）。domains 段 = 域色两段式通道（identity/surface/border 三角色，v1 封闭；promotion 按域色矩阵无描边列）。assets 段 = 素材变量链语义位（W-T3 铺开，铺开后逐一核对）。",
+  "platform": [
+    "--tbox-accent",
+    "--tbox-accent-light",
+    "--tbox-bg-card",
+    "--tbox-bg-page",
+    "--tbox-bg-subtle",
+    "--tbox-bg-warm",
+    "--tbox-border",
+    "--tbox-border-strong",
+    "--tbox-content-max-width",
+    "--tbox-error",
+    "--tbox-fs-body",
+    "--tbox-fs-caption",
+    "--tbox-fs-heading",
+    "--tbox-icon-color",
+    "--tbox-ink",
+    "--tbox-input-bg",
+    "--tbox-input-padding",
+    "--tbox-input-radius",
+    "--tbox-media-item-radius",
+    "--tbox-media-item-size",
+    "--tbox-motion-duration-base",
+    "--tbox-motion-duration-fast",
+    "--tbox-motion-duration-slow",
+    "--tbox-motion-easing-emphasized",
+    "--tbox-motion-easing-standard",
+    "--tbox-page-gutter",
+    "--tbox-primary",
+    "--tbox-primary-dark",
+    "--tbox-primary-light",
+    "--tbox-radius-lg",
+    "--tbox-radius-md",
+    "--tbox-radius-sm",
+    "--tbox-send-btn-size",
+    "--tbox-shadow-lg",
+    "--tbox-shadow-md",
+    "--tbox-shadow-sm",
+    "--tbox-success",
+    "--tbox-text-muted",
+    "--tbox-text-primary",
+    "--tbox-text-secondary",
+    "--tbox-transition-base",
+    "--tbox-transition-fast",
+    "--tbox-warning"
+  ],
+  "domains": [
+    "--tbox-domain-member-accent",
+    "--tbox-domain-member-border",
+    "--tbox-domain-member-surface",
+    "--tbox-domain-parking-accent",
+    "--tbox-domain-parking-border",
+    "--tbox-domain-parking-surface",
+    "--tbox-domain-promotion-accent",
+    "--tbox-domain-promotion-surface",
+    "--tbox-domain-sg-accent",
+    "--tbox-domain-sg-border",
+    "--tbox-domain-sg-surface"
+  ],
+  "assets": [
+    "--tbox-asset-bumpin-bg",
+    "--tbox-asset-home-poster-compact",
+    "--tbox-asset-home-poster-stage",
+    "--tbox-asset-member-login-hero",
+    "--tbox-asset-member-mascot",
+    "--tbox-asset-parking-hero",
+    "--tbox-asset-promotion-activity-header",
+    "--tbox-asset-promotion-coupon-header",
+    "--tbox-asset-sg-header"
+  ]
+}

package/packages/agent-ui-kit/src/theme/global.less

@@ -0,0 +1,99 @@
+@import './tokens.less';
+@import './motion.less';
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+}
+
+body {
+  /* mall-vis 字栈：demo 拉丁栈 + 显式 CJK（demo 依赖容器隐式 CJK，模板面向开放浏览器） */
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'PingFang SC',
+    'Microsoft YaHei', sans-serif;
+  font-size: var(--tbox-fs-body);
+  color: var(--tbox-text-primary);
+  background: var(--tbox-bg-page);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* 顶层容器全宽（渐变底铺满），内容区由各处 max-width:800px 居中（对齐原模板 #app）。 */
+#root {
+  width: 100%;
+  position: relative;
+}
+
+/* 去掉移动端点击高亮 */
+* {
+  -webkit-tap-highlight-color: transparent;
+}
+
+/* 卡片统一外层 = 卡片「卡框」。所有卡片共有的框在这里，单卡组件别重复写：
+   - 间距：卡片与上下元素（工具调用 / 气泡）的间距，与 .tool-calls 一致；
+   - 外观：默认背景(白) / 2px 边框 / 圆角 / 阴影；`overflow:hidden` 把内容裁进圆角；
+   - 入场动效：mount 即播（0.36s 上浮淡入，对齐 mall-vis 消息卡节奏）。
+   值为源码 px（2x 基线、折半渲染）：圆角 var(--tbox-radius-lg)=48≈24（与气泡 48 同口径）、边框 2≈1、阴影 var(--tbox-shadow-sm)≈0 4px 13px。
+   ⚠️ **内边距不在卡框里**——由卡片自己写。卡框给 padding 会让「自带背景色的卡」在外面露一圈白边（卡里套卡）。
+   宽度也不在卡框里：默认占满整列（≈移动端 350~400px 设计宽），紧凑卡自己写 max-width。
+   单卡组件（.tbox-<type>）只画内容；**要整卡换底色 / 出血图，直接在自己 root 上 `background:<色>` 或铺满图**——
+   会铺满卡框、裁进圆角、不出白边（别再自己设圆角，卡框已裁）。不写背景则露卡框默认白底，不透明。 */
+.tbox-card {
+  margin-bottom: 12px;
+  background: var(--tbox-bg-card);
+  border: 2px solid var(--tbox-border);
+  border-radius: var(--tbox-radius-lg);
+  box-shadow: var(--tbox-shadow-sm);
+  overflow: hidden;
+  animation: tbox-card-enter var(--tbox-motion-duration-slow) ease;
+}
+
+@keyframes tbox-card-enter {
+  from {
+    opacity: 0;
+    transform: translateY(16px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .tbox-card {
+    animation: none;
+  }
+}
+
+/* 多卡纵向容器（SDK CardCarousel 多卡分支）：容器内卡片关闭逐卡入场动画——
+   同屏多卡逐张挂载时 0.36s 上浮淡入会交叠抖动；单卡直出与其他场景的入场动画保留
+   （命中卡片本体 .tbox-card：卡框动画在自身规则上，item 中间层无动画规则） */
+.tbox-card-stack .tbox-card {
+  animation: none;
+}
+
+/* 兜底态（未知 cardType / 渲染出错，由 CardRenderer 给外层加此修饰类）：
+   复用卡框，弱化成无阴影的虚线提示框（内边距自带，因为卡框不再给 padding） */
+.tbox-card--fallback {
+  max-width: 80%;
+  padding: 32px 24px;
+  background: var(--tbox-bg-subtle);
+  border: 1px dashed var(--tbox-border);
+  box-shadow: none;
+  color: var(--tbox-text-muted);
+  font-size: var(--tbox-fs-caption);
+}
+
+/* ===== antd-mobile 全局弹层层级（2026-09-04）：业务半屏浮层（门店详情/门店导览）z-index 1100，
+ * Toast/Dialog/Popup 等瞬态反馈弹层默认 1000 会被盖住（门店券行领取的弹出提醒不可见实证）——
+ * 统一提至 1200 置于一切业务浮层之上（antd-mobile 官方 :root:root 双写覆盖约定）===== */
+:root:root {
+  --adm-z-index-mask: 1200;
+}

package/packages/agent-ui-kit/src/theme/motion.less

@@ -0,0 +1,19 @@
+/**
+ * 动效 token（主题轨 W-T2）——过渡节奏与缓动的平台级变量。
+ *
+ * 主题可覆写面：主题包 `html[data-theme='<name>']` 段覆写本文件变量即可整体换节奏
+ * （覆写值须在 contract.json platform 段封闭清单内——doctor 25 校验）。
+ * duration 三档对齐现状众数（fast 0.18s 既有 token 值 / base 0.28s 既有 / slow 0.36s 卡入场）；
+ * easing standard = 既有 transition token 曲线（值零变化）。
+ * 循环动画（spin/pulse/blink/wave）与交错 delay 的节奏属组件语义，不入本族（v1 封闭）。
+ */
+:root {
+  /* duration：交互反馈（按压/hover/快挂载）、面板与弹层过渡、入场主过渡 */
+  --tbox-motion-duration-fast: 0.18s;
+  --tbox-motion-duration-base: 0.28s;
+  --tbox-motion-duration-slow: 0.36s;
+
+  /* easing：标准曲线（= 既有 --tbox-transition-* 曲线）；强调曲线留给主题与后续组件 */
+  --tbox-motion-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --tbox-motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+}

package/packages/agent-ui-kit/src/theme/theme-contract.test.ts

@@ -0,0 +1,69 @@
+/**
+ * 主题契约锁（主题轨 W-T2）：contract.json 单一真源 ↔ kit css 机械一致。
+ *
+ * 断言：
+ * ① tokens.less + motion.less 的 :root 变量集 ⊆ contract.platform（css 演进不漂移清单）；
+ * ② contract 三段非空且全局唯一（无重复键）；
+ * ③ domains/assets 段命名空间前缀正确（--tbox-domain-* / --tbox-asset-*）。
+ *
+ * doctor theme-package-structure 只读 contract.json（node fs），本测试是"css ⊆ json"的仓内锁。
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const themeDir = path.dirname(fileURLToPath(import.meta.url));
+const contract = JSON.parse(readFileSync(path.join(themeDir, 'contract.json'), 'utf-8')) as {
+  platform: string[];
+  domains: string[];
+  assets: string[];
+};
+
+function extractRootVars(file: string): string[] {
+  const css = readFileSync(path.join(themeDir, file), 'utf-8');
+  const names: string[] = [];
+  // 仅 :root 块内声明（行首 --tbox-*，值可含换行；本包 tokens/motion 均为一行一变量）
+  let inRoot = false;
+  for (const line of css.split('\n')) {
+    if (/^:root\s*\{/.test(line)) inRoot = true;
+    else if (inRoot && line.trim() === '}') inRoot = false;
+    else if (inRoot) {
+      const m = line.match(/^\s*(--tbox-[a-z0-9-]+)\s*:/);
+      if (m) names.push(m[1]);
+    }
+  }
+  return names;
+}
+
+describe('主题契约（contract.json）', () => {
+  it('tokens.less + motion.less 的 :root 变量 ⊆ contract.platform', () => {
+    const cssVars = [...extractRootVars('tokens.less'), ...extractRootVars('motion.less')];
+    expect(cssVars.length).toBeGreaterThan(40);
+    const allowed = new Set(contract.platform);
+    const drift = cssVars.filter((v) => !allowed.has(v));
+    expect(drift, `css 变量未登记进 contract.platform：${drift.join(', ')}`).toEqual([]);
+  });
+
+  it('三段非空、全局键唯一、前缀正确', () => {
+    expect(contract.platform.length).toBeGreaterThan(0);
+    expect(contract.domains.length).toBeGreaterThan(0);
+    expect(contract.assets.length).toBeGreaterThan(0);
+    const all = [...contract.platform, ...contract.domains, ...contract.assets];
+    expect(new Set(all).size, '契约清单存在重复键').toBe(all.length);
+    for (const key of contract.domains) expect(key.startsWith('--tbox-domain-')).toBe(true);
+    for (const key of contract.assets) expect(key.startsWith('--tbox-asset-')).toBe(true);
+  });
+
+  it('motion 族 5 键在清单内（主题轨 T-2.1 契约）', () => {
+    for (const key of [
+      '--tbox-motion-duration-fast',
+      '--tbox-motion-duration-base',
+      '--tbox-motion-duration-slow',
+      '--tbox-motion-easing-standard',
+      '--tbox-motion-easing-emphasized',
+    ]) {
+      expect(contract.platform).toContain(key);
+    }
+  });
+});

package/packages/agent-ui-kit/src/theme/theme.ts

@@ -0,0 +1,17 @@
+/**
+ * 主题接线（单一模板统一化 D8/D9）：html[data-theme] 级联单一入口。
+ *
+ * 纯 CSS 主题包经 `html[data-theme='<name>'] { ... }` 覆写 kit 默认 tokens
+ * （specificity 0-1-1 恒胜 :root 0-1-0——主题文件仅需 import 本包 theme 后叠加自身 CSS）。
+ * 无 HELLO 下发 / 无运行时热切换（按项目交付语义；多主题热切换为文档化扩展位）。
+ */
+
+/** 应用主题：设置 document.documentElement[data-theme]（幂等；接线 = import 主题 css（+ 品牌包 brand.js）+ 本函数调用）。 */
+export function applyTheme(themeId: string): void {
+  document.documentElement.dataset['theme'] = themeId;
+}
+
+/** 读当前主题（未设置 → undefined）。 */
+export function currentTheme(): string | undefined {
+  return document.documentElement.dataset['theme'];
+}

package/packages/agent-ui-kit/src/theme/tokens.less

@@ -0,0 +1,79 @@
+/**
+ * 设计 token —— mall-vis 双演示商圈主题（浅色蓝系；⊇ base 26 变量，名字零增减）。
+ *
+ * C 方案下卡片是 client React 组件、不再有 iframe 下发 tokens，
+ * 所以这些设计变量必须落在 client。卡片组件与页面统一用 var(--tbox-*) 引用，
+ * 禁止硬编码十六进制色值 / px 字号。
+ *
+ * 注：这里的 px 会被 postcss-px-to-viewport（750 基准）转成 vw。
+ * 视觉源对照与域色矩阵见 docs/reference/templates.md（视觉体系与域色矩阵）。
+ */
+:root {
+  /* 主色（mall-vis 蓝系） */
+  --tbox-primary: #096bfa;
+  --tbox-primary-dark: #2368ec;
+  --tbox-primary-light: #eaf3ff;
+  --tbox-accent: #096bfa;
+  --tbox-accent-light: #eaf3ff;
+  --tbox-ink: #0b0f17;
+
+  /* 文本 */
+  --tbox-text-primary: #0b0f17;
+  --tbox-text-secondary: #535b6c;
+  --tbox-text-muted: #6f7380;
+
+  /* 背景 */
+  --tbox-bg-page: #fbfcfe;
+  --tbox-bg-card: #ffffff;
+  --tbox-bg-subtle: #f5f7fa;
+  --tbox-bg-warm: #f7faff;
+
+  /* 边框 */
+  --tbox-border: #e1e5ec;
+  --tbox-border-strong: #d3dae6;
+
+  /* 阴影 */
+  --tbox-shadow-sm: 0 8px 26px rgba(38, 59, 92, 0.05);
+  --tbox-shadow-md: 0 12px 32px rgba(24, 82, 177, 0.1);
+  --tbox-shadow-lg: 0 14px 34px rgba(2, 46, 122, 0.08);
+
+  /* 状态色 */
+  --tbox-success: #169e5a;
+  --tbox-warning: #df8b16;
+  --tbox-error: #e42f46;
+
+  /* 字号——按 750/2x 设计稿基线，对标消息气泡（MessageBubble）：
+       正文 .msg-markdown / __text = 25px，次要信息(时间/角色) = 18~19px，标题 h1~h4 = 36/32/30/28px。
+     注意：rootValue 100 + 根字号脚本会把 px 折半渲染（750 稿 → ≈375 手机列），
+     所以这里写的是 2x 值，别按普通 web 的 12/14/16 写（那样渲染出来只有一半、发虚）。 */
+  --tbox-fs-heading: 30px; /* ≈气泡 h3：商品名 / 店名 */
+  --tbox-fs-body: 25px;    /* =气泡正文 */
+  --tbox-fs-caption: 20px; /* ≈气泡次要信息(时间/角色) */
+
+  /* 圆角 */
+  --tbox-radius-sm: 12px;
+  --tbox-radius-md: 18px;
+  --tbox-radius-lg: 48px;
+
+  /* 内容最大宽度（对齐参考 H5）：全宽渐变底 + 内容区 720px 居中。
+     大写 PX 不被 postcss-pxtorem 转换（正则大小写敏感），保持固定像素。 */
+  --tbox-content-max-width: 720PX;
+  /* 页面水平栅格：欢迎区、主卡、快捷入口、输入区、消息气泡和消息卡片共用。 */
+  --tbox-page-gutter: 16PX;
+
+  /* 媒体缩略图 */
+  --tbox-media-item-size: 174px;
+  --tbox-media-item-radius: 12px;
+
+  /* 输入框 */
+  --tbox-input-bg: rgba(255, 255, 255, 0.7);
+  /* 输入条跨过 450PX 根字号阈值时保持固定高度，仅横向伸缩。 */
+  --tbox-input-radius: 25PX;
+  --tbox-input-padding: 10PX 12PX;
+  --tbox-send-btn-size: 22PX;
+  --tbox-icon-color: #4b6282;
+
+  /* 过渡（兼容别名——值引用 motion 族，主题覆写走 --tbox-motion-*） */
+  --tbox-transition-fast: var(--tbox-motion-duration-fast) var(--tbox-motion-easing-standard);
+  --tbox-transition-base: var(--tbox-motion-duration-base) var(--tbox-motion-easing-standard);
+}

package/packages/agent-ui-kit/src/utils/haptics.test.ts

@@ -0,0 +1,51 @@
+/**
+ * 轻触反馈用例：核心契约是「永不影响调用方」——桥失败、API 缺席都必须静默降级。
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ callJsapi: vi.fn() }));
+vi.mock('@tbox.cn/app-sdk/client', () => ({ callJsapi: mocks.callJsapi }));
+
+import { hapticTap, resetHapticBridgeState } from './haptics';
+
+afterEach(() => {
+  mocks.callJsapi.mockReset();
+  resetHapticBridgeState();
+  vi.unstubAllGlobals();
+});
+
+describe('hapticTap', () => {
+  it('H1 容器态走 JSAPI 桥的轻档震动', () => {
+    mocks.callJsapi.mockResolvedValue({});
+    hapticTap();
+    expect(mocks.callJsapi).toHaveBeenCalledWith('vibrateShort', { type: 'light' });
+  });
+
+  it('H2 桥不可用 → 回退 navigator.vibrate，且不再重复试桥', async () => {
+    const vibrate = vi.fn();
+    vi.stubGlobal('navigator', { vibrate });
+    mocks.callJsapi.mockRejectedValue({ code: 'BRIDGE_UNAVAILABLE' });
+
+    hapticTap();
+    await vi.waitFor(() => expect(vibrate).toHaveBeenCalledTimes(1));
+
+    // 第二次不再走桥（避免每次手势都积累一次超时等待）
+    hapticTap();
+    expect(mocks.callJsapi).toHaveBeenCalledTimes(1);
+    expect(vibrate).toHaveBeenCalledTimes(2);
+  });
+
+  it('H3 平台无 vibrate API（如 iOS Safari）：静默，不抛错', async () => {
+    vi.stubGlobal('navigator', {});
+    mocks.callJsapi.mockRejectedValue({ code: 'BRIDGE_UNAVAILABLE' });
+    expect(() => hapticTap()).not.toThrow();
+    await vi.waitFor(() => expect(mocks.callJsapi).toHaveBeenCalled());
+  });
+
+  it('H4 vibrate 抛错（权限拒绝）也被吞掉', () => {
+    vi.stubGlobal('navigator', { vibrate: () => { throw new Error('denied'); } });
+    resetHapticBridgeState();
+    mocks.callJsapi.mockRejectedValue({ code: 'BRIDGE_UNAVAILABLE' });
+    expect(() => hapticTap()).not.toThrow();
+  });
+});

package/packages/agent-ui-kit/src/utils/haptics.ts

@@ -0,0 +1,44 @@
+/**
+ * 轻触反馈（haptic tap）——手势跨过阈值那一刻的确认信号。
+ *
+ * 分层降级，全部 fail-soft：反馈缺失不该影响任何功能路径。
+ * 1. 支付宝 web-view 容器：走 JSAPI 桥 my.vibrateShort（type: 'light' 对应轻档）
+ * 2. 普通浏览器：navigator.vibrate（Android Chrome 支持；iOS Safari 无此 API，静默跳过）
+ *
+ * 注意 iOS 上无论哪条路径都可能无感——Safari 不开放 Taptic Engine 给网页，
+ * 容器内是否有感取决于宿主 App 的实现。调用方不应依赖它的成功与否。
+ */
+import { callJsapi } from '@tbox.cn/app-sdk/client';
+
+/** 极短时长（ms）：轻点级别，不是提示级别的长震。 */
+const TAP_DURATION_MS = 10;
+
+let bridgeUnavailable = false;
+
+/** 触发一次轻触反馈。永不抛错、永不 reject——失败即静默。 */
+export function hapticTap(): void {
+  // 桥不可用时不再重试：每次手势都试一遍会积累无意义的超时等待
+  if (!bridgeUnavailable) {
+    void callJsapi('vibrateShort', { type: 'light' })
+      .catch((e: unknown) => {
+        if ((e as { code?: string })?.code === 'BRIDGE_UNAVAILABLE') bridgeUnavailable = true;
+        vibrateFallback();
+      });
+    return;
+  }
+  vibrateFallback();
+}
+
+function vibrateFallback(): void {
+  try {
+    const nav = typeof navigator === 'undefined' ? null : navigator;
+    nav?.vibrate?.(TAP_DURATION_MS);
+  } catch {
+    /* 权限或平台不支持：静默 */
+  }
+}
+
+/** 单测用：重置桥可用性记忆。 */
+export function resetHapticBridgeState(): void {
+  bridgeUnavailable = false;
+}

package/packages/agent-ui-kit/src/utils/pull-down-machine.test.ts

@@ -0,0 +1,188 @@
+/**
+ * createPullDownMachine 全转移表回归（纯逻辑，node 环境）：
+ * - 实时门控取代 touchStart 锁定（未到顶 move 重锚 → 到顶后从最近锚点测距）；
+ * - 顶部门槛跨越（pulling→ready→touchEnd shouldLoad）/ 不足回弹 / noMore 封顶 + holdNoMore；
+ * - isLoading 全忽略；wheel 累积语义（顶部向上滚累积越阈即发，发后/离顶/向下滚归零）；reset 归零。
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  createPullDownMachine,
+  DAMPING,
+  PULL_DOWN_THRESHOLD,
+  PULL_TRIGGER_OFFSET,
+  WHEEL_DISTANCE_SCALE,
+  WHEEL_TRIGGER_ACCUM,
+} from './pull-down-machine';
+
+/** 越过触发线所需的手指行程（阈值按内容位移定义，手指行程 = 位移 / 阻尼）。 */
+const FINGER_OVER = PULL_TRIGGER_OFFSET / DAMPING + 10;
+
+describe('createPullDownMachine（touch 路径）', () => {
+  it('M1 二段手势：未到顶 move×3 重锚 → 到顶后从最近锚点测距（实时门控）', () => {
+    const m = createPullDownMachine();
+    m.touchStart(300);
+    // 未到顶：重锚 + 状态不动（无 preventDefault）
+    expect(m.touchMove({ clientY: 250, isAtTop: false, hasMore: true, isLoading: false })).toEqual({ preventDefault: false });
+    expect(m.touchMove({ clientY: 200, isAtTop: false, hasMore: true, isLoading: false })).toEqual({ preventDefault: false });
+    m.touchMove({ clientY: 100, isAtTop: false, hasMore: true, isLoading: false });
+    // 到顶后：从 100 测距（若未重锚会从 300 测出巨值）
+    const r = m.touchMove({ clientY: 130, isAtTop: true, hasMore: true, isLoading: false });
+    expect(r.preventDefault).toBe(true);
+    expect(m.getState().distance).toBe(30 * DAMPING);
+    expect(m.getState().status).toBe('pulling');
+  });
+
+  it('M2 门槛跨越：distance > PULL_TRIGGER_OFFSET → ready；touchEnd 触发 shouldLoad 并进入 loading', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    m.touchMove({ clientY: 100 + FINGER_OVER, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState().status).toBe('ready');
+    const end = m.touchEnd({ hasMore: true });
+    expect(end).toEqual({ shouldLoad: true, holdNoMore: false });
+    expect(m.getState()).toEqual({ status: 'loading', distance: PULL_DOWN_THRESHOLD });
+  });
+
+  it('M2b 触发线以下：保持 pulling，松手不加载（位移≠意图）', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    // 差一点越线：阈值按内容位移定义，故手指行程取 (触发线 - 1) / 阻尼
+    m.touchMove({ clientY: 100 + (PULL_TRIGGER_OFFSET - 1) / DAMPING, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState().distance).toBeLessThan(PULL_TRIGGER_OFFSET);
+    expect(m.getState().status).toBe('pulling');
+    expect(m.touchEnd({ hasMore: true })).toEqual({ shouldLoad: false, holdNoMore: false });
+  });
+
+  it('M3 不足阈值 touchEnd：回弹 idle（shouldLoad=false）', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    m.touchMove({ clientY: 120, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState().status).toBe('pulling');
+    expect(m.touchEnd({ hasMore: true })).toEqual({ shouldLoad: false, holdNoMore: false });
+    expect(m.getState()).toEqual({ status: 'idle', distance: 0 });
+  });
+
+  it('M4 deltaY<=0（上滑）：状态回 idle、distance 归零', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    m.touchMove({ clientY: 140, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState().status).toBe('pulling');
+    m.touchMove({ clientY: 90, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState()).toEqual({ status: 'idle', distance: 0 });
+  });
+
+  it('M5 hasMore=false：noMore 态 + 距离封顶 + touchEnd holdNoMore', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    m.touchMove({ clientY: 400, isAtTop: true, hasMore: false, isLoading: false });
+    expect(m.getState().status).toBe('noMore');
+    expect(m.getState().distance).toBe(PULL_DOWN_THRESHOLD); // 封顶
+    expect(m.touchEnd({ hasMore: false })).toEqual({ shouldLoad: false, holdNoMore: true });
+    expect(m.getState().status).toBe('noMore'); // 保留（wrapper 定时 reset）
+  });
+
+  it('M6 isLoading=true：touchMove 全忽略', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    const r = m.touchMove({ clientY: 400, isAtTop: true, hasMore: true, isLoading: true });
+    expect(r.preventDefault).toBe(false);
+    expect(m.getState()).toEqual({ status: 'idle', distance: 0 });
+  });
+});
+
+describe('createPullDownMachine（wheel 路径）', () => {
+  it('W1 顶部向上滚累积：分次未达阈不触发，越阈触发且归零', () => {
+    const m = createPullDownMachine();
+    const step = WHEEL_TRIGGER_ACCUM / 2; // 两步刚好到线（不越），第三步越线
+    expect(m.wheel({ deltaY: -step, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+    expect(m.wheel({ deltaY: -step, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+    expect(m.wheel({ deltaY: -10, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: true }); // 越线
+    expect(m.wheel({ deltaY: -step, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false }); // 触发后归零重计
+  });
+
+  it('W1b 单次大 deltaY 不足以触发：滚轮需连续意图（回归「一滚即加载」）', () => {
+    const m = createPullDownMachine();
+    expect(m.wheel({ deltaY: -(WHEEL_TRIGGER_ACCUM - 1), isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+  });
+
+  it('W2 离顶 / 向下滚：累积清零', () => {
+    const m = createPullDownMachine();
+    const near = WHEEL_TRIGGER_ACCUM - 10; // 差一点越线
+    m.wheel({ deltaY: -near, isAtTop: true, hasMore: true });
+    m.wheel({ deltaY: 10, isAtTop: true, hasMore: true }); // 向下滚清零
+    expect(m.wheel({ deltaY: -near, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+    m.wheel({ deltaY: -near, isAtTop: false, hasMore: true }); // 离顶清零
+    expect(m.wheel({ deltaY: -near, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+  });
+
+  it('W3 wheel 驱动与拖拽同尺度的视觉：累积中 pulling，越阈直接进 loading', () => {
+    const m = createPullDownMachine();
+    const half = WHEEL_TRIGGER_ACCUM / 2;
+    m.wheel({ deltaY: -half, isAtTop: true, hasMore: true });
+    expect(m.getState().status).toBe('pulling');
+    // 累积按触发线之比换算到拖拽尺度，两条路径的文案切换点因此重合
+    expect(m.getState().distance).toBeCloseTo(half * WHEEL_DISTANCE_SCALE);
+
+    m.wheel({ deltaY: -WHEEL_TRIGGER_ACCUM, isAtTop: true, hasMore: true }); // 越线
+    // 没有「松手」这一刻，越阈即发：直接进 loading，不经 ready
+    expect(m.getState().status).toBe('loading');
+  });
+
+  it('W4 wheelIdle：停止滚动后清掉累积与视觉，文案不卡在拉动态', () => {
+    const m = createPullDownMachine();
+    const near = WHEEL_TRIGGER_ACCUM - 10;
+    m.wheel({ deltaY: -near, isAtTop: true, hasMore: true });
+    expect(m.getState().status).toBe('pulling');
+    m.wheelIdle();
+    expect(m.getState()).toEqual({ status: 'idle', distance: 0 });
+    // 累积也已清零：复位后需重新攒够才触发
+    expect(m.wheel({ deltaY: -near, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+  });
+
+  it('W4b 加载中 wheel 全忽略：惯性滚动不得把 loading 打回 pulling（动画弹跳根因）', () => {
+    const m = createPullDownMachine();
+    m.wheel({ deltaY: -(WHEEL_TRIGGER_ACCUM + 10), isAtTop: true, hasMore: true });
+    expect(m.getState().status).toBe('loading');
+    const during = m.getState();
+
+    // 触控板惯性在加载期间继续送 wheel
+    expect(m.wheel({ deltaY: -200, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+    expect(m.getState()).toEqual(during);
+    // 显式 isLoading 同样短路
+    expect(m.wheel({ deltaY: -200, isAtTop: true, hasMore: true, isLoading: true })).toEqual({ shouldLoad: false });
+    expect(m.getState()).toEqual(during);
+  });
+
+  it('W4c wheelIdle 不打断加载：loading 期间只清累积，视觉留给加载完成时的 reset', () => {
+    const m = createPullDownMachine();
+    m.wheel({ deltaY: -(WHEEL_TRIGGER_ACCUM + 10), isAtTop: true, hasMore: true });
+    expect(m.getState().status).toBe('loading');
+    m.wheelIdle();
+    expect(m.getState().status).toBe('loading'); // 文案不该被打回「历史记录」
+  });
+
+  it('W5 hasMore=false：wheel 同样进 noMore 且距离封顶，不发加载', () => {
+    const m = createPullDownMachine();
+    expect(m.wheel({ deltaY: -500, isAtTop: true, hasMore: false })).toEqual({ shouldLoad: false });
+    expect(m.getState().status).toBe('noMore');
+    expect(m.getState().distance).toBe(PULL_DOWN_THRESHOLD);
+  });
+});
+
+describe('createPullDownMachine（reset）', () => {
+  it('R1 reset：status/distance/wheelAccum 全归零（G9 noMore 复活）', () => {
+    const m = createPullDownMachine();
+    m.touchStart(100);
+    m.touchMove({ clientY: 100 + FINGER_OVER, isAtTop: true, hasMore: false, isLoading: false });
+    expect(m.getState().status).toBe('noMore');
+    m.wheel({ deltaY: -50, isAtTop: true, hasMore: true });
+    m.reset();
+    expect(m.getState()).toEqual({ status: 'idle', distance: 0 });
+    // noMore 复活：reset 后 hasMore=true 的正常下拉可用
+    m.touchStart(100);
+    m.touchMove({ clientY: 100 + FINGER_OVER, isAtTop: true, hasMore: true, isLoading: false });
+    expect(m.getState().status).toBe('ready');
+    // wheelAccum 已归零
+    expect(m.wheel({ deltaY: -30, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+    expect(m.wheel({ deltaY: -30, isAtTop: true, hasMore: true })).toEqual({ shouldLoad: false });
+  });
+});