dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/shotcraft/upstream/references/shots/data/gauge-readout-moves.md

@@ -0,0 +1,45 @@
+---
+name: gauge-readout-moves
+一句话: 仪表读数两式——needle-sweep-selftest 满弧扫针（点火自检指针甩满全弧再回落真值）与 tape-scroll-fixed-pointer 滚带定针（针不动刻度带滚过+冲刺刹车）
+适用: dashboard 开场仪式/性能指标揭晓；A 多表盘开机感，B 单指标大跳变
+时长: A 140f（4.7s）/ B 150f（5s）
+能量: 中高（机械仪式型）
+---
+
+## 意图
+把"报数值"做成仪表的身体动作：A 是汽车点火自检——卡片里三个并排表盘
+指针先"唰"地甩满全弧（270°）、扫过的刻度依次点亮，再弹簧回落定格真实值，
+多表错峰成波浪，落定同帧盘下数值弹出，先亮量程再报数，开场宣誓感；
+B 是飞机空速带语法——读数窗 + 指针钉死画面中线，贯穿全画高的刻度带整体从窗后滚过，先顶着旧上限慢爬、升级后冲刺
+（峰值 ~100px/f）、末尾 spring 刹车带回摆过冲，"世界动、针不动"，
+数值大小变成看得见的位移距离。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A needle-sweep-selftest | 表面与外环点亮 → 指针去程 12f ease-out 甩满弧（扫过的刻度依次点亮、24f 内回落）→ 弹簧回程 ~8° 过冲回摆落真值；三表错峰 4f；落定同帧盘下数值 overshoot 弹出、指标名淡入，全部落定后自检胶囊 Running self-test… → Ready to render | dashboard 开场/系统就绪仪式 |
+| B tape-scroll-fixed-pointer | 全画高刻度带 translate：慢爬顶住旧上限线→上限线断开→预备回拉 5→冲刺 22f（峰值 ~100px/f，纵向运动模糊）→spring 刹车过冲回摆停位，新上限 bug 停进指针；窗内读数同步刷新 | 单指标大跳变（性能翻倍/配额提升） |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 甩弧幅度 | 满量程 270°，到顶即回程 | 只甩到真值=没有自检仪式感；满弧再回落才是"先亮量程"；去程扫过的刻度（含红区）依次点亮 |
+| A 过冲 | 回落带 ~8° 回摆（按行程反算弹簧阻尼） | 无过冲读作电子表；过冲=机械指针的质量 |
+| A 错峰 | 4f/表（左→中→右） | 齐甩读作复制粘贴；错峰成波浪 |
+| B 冲刺速度 | 5px/单位、峰值 ~100px/f（大跳变段） | 慢了读作匀速爬升，"世界动"不成立；带子越长越大，越要配纵向运动模糊 |
+| B 刹车 | spring 过冲（冲过头再弹回停位） | 词汇原案的回摆是"哐"的来源，直停可惜 |
+| 真静止 | 停位后 ≥30f 全锁死（A 末表落定 ~66f、B 110f 锁常数） | 指针类最忌尾漂 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 同批 ring-close-overfill（合环过盈）改改再看无附言——环形进度类
+  待重做，别急着当第三式并入
+- A 的表盘是自绘 SVG（弧刻度+指针），实战贴真 dashboard 时优先找
+  页面里现成的 gauge 组件特写，没有再造
+- 声音：A 甩针一声"唰"+落定"嗒"（多表错峰各一声）；B 冲刺段
+  低频滚动声、刹车一声闷"哐"
+
+## 参考实现
+demos/data/gauge-readout-moves/
+（NeedleSweepSelftest.tsx / TapeScrollFixedPointer.tsx）

package/lib/motion/shotcraft/upstream/references/shots/data/scroll-brake-moves.md

@@ -0,0 +1,46 @@
+---
+name: scroll-brake-moves
+一句话: 长卷急刹两式——changelog-scroll-brake 基本款（高速长卷指数减速精准停位+目标抬升）与 brake-reticle-lock 组合款（急刹帧同帧准星咬合）
+适用: changelog/发布史/长列表段落："一直在发货，今天这条最大"；要给停点更强打击感用 B
+时长: A 4–5s / B 5s
+能量: 高开中收（速度对比型）
+标签: rhythm
+---
+
+## 意图
+Linear changelog 视频语法：一整年的更新日志作为长卷高速掠过
+（糊成色带），指数减速精准急刹停在本次发布那条上，该条抬升离面
+高亮、其余退暗——密度感讲"一直在发货"，急停讲"今天这条最大"。
+B 是组合变异：急刹帧**同帧**四个 L 角标从画外飞入咬合锁定停点
+条目——急刹的"哐"与咬合的"咔"叠在同一帧共振（组合命门：
+角标起跳帧=列表首停帧，错开退化成两招并置）。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A changelog-scroll-brake | translateY 扫 ~2400px（cubic-bezier(.45,0,.06,1)：~5f 拉满速再长尾指数式减速，共 50f），纵向方向性 blur 由帧间位移差分驱动（×0.32 封顶 30px，停稳自动清零）；停点行 scale 1.03 抬升+阴影+2px 强调色描边，其余 opacity 退 0.38 | changelog 段落基本款 |
+| B brake-reticle-lock | 滚动三段：sin-in 加速→cubic-out 猛减速冲过头 +30px→回弹落定；纵向方向性 blur=v×0.15 封顶 32px；角标从 ±620/±320 画外 Easing.back(2.4) 飞入咬合，高亮 6f 内完成、标签 back(2.6) 弹出 | 停点需要更强打击感的高光段 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 减速曲线 | A 快起步 + 长尾减速（bezier .45,0,.06,1）；B 加"冲过头 30px 回弹" | 匀速滚读作跑马灯；B 的过头回弹是"哐"的来源 |
+| blur 驱动 | 帧间位移差分 `|p(f)-p(f-1)|`×系数 | 手排模糊关键帧必然对不上速度；差分法帧确定（模式已沉为 assets/lib/helpers/motion.ts velocityAt） |
+| 行高节奏 | 72/94/116 三档错落 | 等高行高速掠过时色带无节奏 |
+| 停位 | 目标行停画面纵向正中 | 停偏读作事故 |
+| B 共振帧 | 角标挂载起跳帧 = 列表首次停住帧（严格同帧） | 组合命门，错 2f 以上就散 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 timeline-travel 分工：本卡纵向列表急刹停"最新"，
+  那卡横向时间轴旅行看"历史"——同片双用时先后错开且各 ≤1 次
+- 高速段条目内容不用真实可读文本——反正糊成色带，占位灰块即可；
+  停点条目必须出版级真内容（Q10）
+- 停点后其余行退暗 0.38 是构图动作：别退到 0（上下文消失）
+- 声音：高速段低频 riser 铺垫，急刹一声 impact；B 咬合帧
+  再叠一声"咔"（与 impact 同帧不同声部）
+
+## 参考实现
+demos/data/scroll-brake-moves/
+（BrakeReticleLock.tsx / ChangelogScrollBrake.tsx）

package/lib/motion/shotcraft/upstream/references/shots/data/timeline-travel.md

@@ -0,0 +1,44 @@
+---
+name: timeline-travel
+一句话: 时间轴横移——镜头沿水平刻度轴加速掠过版本刻度，每过一格卡片弹立短停，末刻度急停推近
+适用: changelog/里程碑/发展史段落（"我们一直在发货"的另一种拍法）；与 scroll-brake-moves 分工：那卡是纵向列表急刹，本卡是横向时间旅行
+时长: 4–5s
+能量: 中高（加速→急刹的节奏型镜头）
+标签: camera
+---
+
+## 意图
+把产品的版本史拍成一次沿时间轴的旅行（《反恐王国》片头判例）：
+镜头缓起→冲刺→急刹三段变速横移，v1.0/v2.0/v3.0 刻度依次掠过，
+每过一格对应卡片从刻度线上 spring 弹立——历史在窗外闪过，
+急停在"今天"并推近。速度本身讲"发展快"，急停讲"现在最重要"。
+
+## 动作阶段
+| 阶段 | 帧段参考 | 内容 |
+|------|------|------|
+| 1 静置 | f0–12 | 空轴 + 首刻度定住 |
+| 2 加速掠过 | ~f12–100 | 世界层 translateX 分段缓动：缓起→冲刺→末 12% 急刹 |
+| 3 弹卡 | 掠过中 | 相机扫过刻度前 6f 卡片起弹（spring damping ~11 明显过冲），底边为轴 scaleY 立起 |
+| 4 急停推近 | 急停帧起 10f | scale 1→1.28 推近末刻度（out cubic），接静止 ≥30f |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 变速曲线 | 输入断点 [0,0.15,0.88,1]→输出 [0,0.055,0.9,1] | 中段不够快就没有"旅行感"；全程匀速即廉价 PPT |
+| 弹立时机 | 相机到达刻度前 6f 起弹，由 camXAt 反查 | 到了才弹观众已经错过；早太多读作预告 |
+| 刻度密度 | 主刻度 3–5 个 + 次刻度小点若干 | 次刻度点是速度感的参照物，删掉就感觉不到快 |
+| 急停推近 | 1→1.28 / 10f | 不推近急停就只是"停了"，推近才是"到了" |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 中段冲刺快到卡片糊时可叠 CameraMotionBlur（只包快速段，轮 #8 判例）
+- 急停后静止预算前置：demo 首版静止只有 25f 不达标，急停帧前移才够
+  ——排时间线时先给末段留 ≥30f 再倒推行程
+- 每张弹立卡片是信息位：实战放真实版本亮点截图/一句话，
+  掠过速度要保证至少末两张能读（Q6 同源）
+- 声音：每次弹立一声轻打点，急停一声 impact（S2 同源）
+
+## 参考实现
+demos/data/timeline-travel/
+（TimelineTravel.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/assemble-then-type-flyin.md

@@ -0,0 +1,63 @@
+---
+name: assemble-then-type-flyin
+一句话: 空的暗底网格上，无文字的组件骨架先从四面八方飞入贴合；随后各处文字逐字从 3D 空间旋转着飞来落位，先大标题后小标注，全部落位后页面成形
+适用: 页面/海报"自己长出来"的开场；排版类产品的能力展示；从骨架到成稿的两段式叙事
+时长: 约5.6s（168f@30fps）
+能量: 中高（骨架段稀疏、文字段密集，能量单调上升到收尾）
+---
+
+## 意图
+把"页面生成"拆成两个语义清楚的阶段：先立骨架（框、卡片、分隔线、
+色块，全部无字），再填文字。文字用逐字 3D 旋转落位，是因为骨架段
+只有平面位移——两段的运动维度必须不同，否则观众读不出"这是第二步"。
+
+## 动效核心
+- demo 成形后是 video-shotcraft 的暗场发布页（graphite look，胶片金 accent2 是唯一强调色；导航条是镜刻标志 +
+  video-shotcraft 字标，大标题是品牌短句「Frame motion. / Craft the shot.」），
+  1920×1080 原生坐标；开场第 1 帧先有 12 栏版式参考线，骨架齐后退淡
+- 10 个骨架件（导航条、调色台卡 + 胶片画面色块、镜刻标志、三只色轮圈、分隔线、CTA、次按钮、三枚指标块）
+  按起飞帧 6/10/15/19/23/27/31/35/39/44 依次飞入，每件 16f `EASE.overshoot` 过冲贴合，
+  `from` 位移 120–420px + ±7° 旋转（旋转晚 4f 收敛）
+- 骨架运动中按真实速度（px/帧）给方向性运动模糊（`SpeedBlur` ×0.32，上限 18px），静止即为 0
+- 19 个文字块按起始帧 58→114 依次开始：112px 衬线大标题最先（58/66），
+  然后导航、eyebrow、说明句、按钮字（76–95），指标数字（96–102），最后各处 mono 小标注（104–114）
+- 逐字 3D：每个字符持有确定性种子随机的
+  `dx ±260px / dy ±200px / dz −200→−760 / rotateX ±170° / rotateY ±190° /
+  rotateZ ±120°`，走 `perspective(900px) translate3d + rotateX/Y/Z`，
+  每字 16f `EASE.snappy` 落位，飞行中按离焦距离给景深模糊，`a>=1` 时 transform 直接设 `none`
+- 块内字符间隔自适应：`step = clamp((128 − start − 16)/字符数, 0.35, 1.6)` 帧
+  ——保证不论块多长都在 f128 前落完，尾段留 40f 整页静止呼吸（1.5% 极缓推近）
+- 落定后的"定稿"一笔：CTA 由描边通电成金色实底（118–132），胶片画面被一道金色竖线从 log 灰片
+  擦除成暖调成片（124–146），三只色轮控制点同步从中性位推到偏色位
+- 随机全部来自 `rand(i) = frac(sin(i*127.1 + 311.7) * 43758.5453)`，
+  确定性、可 seek
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 骨架时序 | 10 件，起飞帧 6→44（间隔 4–5f） | 骨架段占前 30%；压缩到 20f 内就和文字段糊在一起 |
+| 骨架飞入 | overshoot、16f、位移 120–420px + ±7° | 与 `scanline-assemble-flyin` 同一手法，去掉扫描线后靠时序读顺序 |
+| 骨架残影 | 方向性运动模糊，按速度 ×0.32、封顶 18px | 只在快速段出现；常驻模糊读作失焦 |
+| 两段断点 | 骨架齐（f50）→ 文字起（f58）留 8f，参考线同期退淡 | 没有这半拍观众读不出"这是第二步" |
+| 文字起点 | 大标题 58/66，小标注 104→114 | 大字先落是可读性要求：小字先落观众会去读小字 |
+| 逐字位移 | dx ±260 / dy ±200 / dz −200→−760 | dz 是"从远处来"的主力；只给 dx/dy 就成了平面散入 |
+| 逐字旋转 | rotateX/Y/Z 各 ±120°–190° | 大角度才有"翻着飞"的手感；±30° 只像抖动 |
+| perspective | 900px（写在每个字符自己的 transform 里） | 112px 大字配 600px 会过度畸变；1400px 以上 3D 感基本消失 |
+| 字间隔 | clamp((128−start−16)/n, 0.35, 1.6) 帧 | 上限 1.6f 是"逐字可辨"的下限速度 |
+| 落位清零 | a>=1 → transform:'none' | 不清零会留下 19 个块的合成层，长片会掉帧 |
+
+## 已知坑
+- 字符 span 走正常排版流（`display:inline-block`），动画只动 transform——
+  不要用绝对定位逐字摆位，换文案就全乱
+- 空格字符必须显式塞成不换行空格（代码里用 `ch === ' ' ? '\u00a0' : ch`），
+  否则 inline-block 的空 span 宽度归零，词间距消失
+- `start` 是手写的 19 个数值，换文案（尤其字符数变化大时）要回看
+  最后一块是否仍在 f128 前落完；`step` 只保证块内，不保证块间
+- 内容是 video-shotcraft 的示例发布页（标题 / 指标 / 色轮标注），落地换成项目自己的；
+  GOLD（graphite 的 accent2 `#e4c58a`）为强调色槽位，CTA 字色随通电由金转深要一起换
+- 与 `scanline-assemble-flyin` 的区别是**没有扫描线**：那张靠扫描线
+  解释顺序，这张靠"先骨架后文字"的两段式解释顺序，两者不要混用
+
+## 参考实现
+demos/effects/assemble-then-type-flyin/
+（AssembleThenTypeFlyin.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/aurora-bloom-bg-flip.md

@@ -0,0 +1,54 @@
+---
+name: aurora-bloom-bg-flip
+一句话: 浅灰底从底部升起紫橙柔焦 blob，随后整个底色在约 0.36s 内压暗到近黑、blob 压成余晖；文案同步 blur-out 换句 blur-in，换句间留空档不 cross-fade
+适用: 叙事转折点（"多年以来…→一切都变了"）；品牌片从铺垫拉到重音的那一拍；深浅色系之间的段落切换
+时长: 约5.2s（156f@30fps）
+能量: 由低到高（前 2/3 是酝酿，压暗那一瞬是全片重音）
+---
+
+## 意图
+把"底色反转"当成重音符号用：前 56% 让极光慢慢升起、观众适应浅底，
+然后用不到 0.4s 把整个画面压到近黑——这一下比任何缩放/闪白都更像
+"翻页"。文案的换句必须卡在反转之后，且中间留空档，让观众先接住画面
+变化再读新句。
+
+## 动效核心
+- 三层 `blur(60px)` blob 从画框底部升起：主紫 `rgba(107,79,224,.85)`
+  90%×85%、橙核 `rgba(217,122,74,.9)`、白色融边 `rgba(255,255,255,.8)`
+- 升起 `seg(0.04→0.56, outCubic)`：`translateY 32%→−6%` + `scale 1→1.25`
+- 反转 `flip = seg(0.57→0.64, inOutQuad)`（归一化 0.07 ≈ 0.36s）：
+  底色 `mix([236,236,236] → [10,10,18])`，blob opacity 1→0.4 压成余晖，
+  白色融边层 `1−flip` 直接收掉
+- 橙核独立 `translateX ±8%`（2.2 周期/全片）横向慢漂，让 blob 内部
+  有相对运动而不是整块升降
+- A 句逐词 `blur 0→8px` + 淡出（t 0.40 起、stagger 0.04、各 0.10、inQuad）；
+  B 句逐词 `outQuint` blur-in（t 0.70 起、stagger 0.05、各 0.11），落位后 0.09 内
+  由 DEEPP 紫收色到白，t≈0.90 定稿后静止 ≈0.5s
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| blob 模糊/尺寸 | blur(60px)，主层 90%×85%，容器 inset −10% | 模糊小于 40px 就看得出是圆，成了"色球"不是"光" |
+| 升起 | translateY 32%→−6% + scale 1→1.25，t 0.04→0.56 outCubic | 占掉一半以上时长是故意的：酝酿越长，反转越有分量 |
+| 反转时长 | t 0.57→0.64 inOutQuad ≈ 0.36s | **命门**：拉到 1s 就不是重音而是渐变过场 |
+| 底色 | #ececec → #0a0a12（不是纯黑） | 纯黑会让余晖 blob 边缘出现色阶断层 |
+| blob 压暗 | opacity 1→0.4，白色融边层同步归零 | 不压暗 blob，暗场里紫橙会过曝糊成一团 |
+| 橙核漂移 | translateX ±8%，2.2 周期/全片 | 幅度到 15% 就看得出是"一个球在动" |
+| A 句 blur-out | 逐词 stagger 0.04、各 0.10、inQuad、blur→8px | inQuad 让消失是加速的，读作"被光吞掉" |
+| B 句 blur-in | 逐词 stagger 0.05、各 0.11 outQuint + 0.09 内紫→白 | 收色比入场晚一点，落定瞬间才转白，是"定稿"的信号 |
+| 换句空档 | A 收完 t≈0.58 → B 起 0.70（≈0.6s 无字） | cross-fade 会把两句糊在一起，空档才读出"翻篇" |
+
+## 已知坑
+- 白色融边层（blobC）只在浅底成立，反转时必须 `1−flip` 收掉，
+  否则暗场里留一团灰雾
+- DEEPP/PURPLE 是这个效果的**本体光色**，不是品牌色槽位；要换成项目色
+  必须 blob 三层 + B 句文字色整组一起换，只换文字色会和背景脱节
+- demo 文案是 video-shotcraft 的叙事转折（"Promos took weeks" / "Meet video-shotcraft"，
+  词数与字长贴近原片的 "For many years" / "everything changed"），逐词
+  stagger 的节奏依赖词数与字长，换句要回调 0.04/0.06 两个间隔
+- 底色用 JS 逐帧写 `background`（`mix()` 出实色），不要用 CSS transition，
+  否则 seek 到任意帧时颜色不确定
+
+## 参考实现
+demos/effects/aurora-bloom-bg-flip/
+（AuroraBloomBgFlip.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/brand-frame-snap.md

@@ -0,0 +1,58 @@
+---
+name: brand-frame-snap
+一句话: 品牌色画框语法——一圈粗纯色画框先于内容长出包住全屏，录屏窗口落进框内；模式切换时整圈画框同帧硬翻色+窗内布局同帧换，一个 borderColor 干完章节导航/状态提示/品牌露出三件事
+适用: 双模式/双章节产品片的全片包装层（蓝=模式A、绿=模式B 颜色编码）；真实录屏素材的品牌化包裹
+时长: 单次翻色 ~4.7s（140f）；画框本身可全片驻场
+能量: 中（翻色瞬间高，其余时间是安静的包装层）
+标签: transition
+---
+
+## 意图
+真实录屏直接铺满屏没有品牌存在感，加 logo 水印又廉价。本卡用一圈
+粗品牌色画框把录屏"装裱"起来：画框**先于内容出现**（先立画框再放
+画，仪式感），之后画框颜色成为全片的语义编码——demo 里钴蓝=Design、
+橘红=Dev Mode（原片是蓝/绿；关键是色相对冲 + 明度差）。章节切换时整圈画框一帧内硬翻色，无渐变，颜色硬切就是"换挡"
+声效的视觉等价物；窗内布局同帧 A→B、角标与徽标同步换字，三处同帧
+共振把"模式切换"砸实。与 theme-switch-moves 分工：那换的是 UI 本体
+肤色（有扫过边界），本卡换的是"画框"这个包装层（同帧无边界），
+语义是模式/章节切换不是主题切换。
+
+## 动效核心
+- 画框用 4 条实体色带（非 border 属性），厚度 0→60px snappy 19f
+  长出（第 2 帧就有可见框）；洞口是 22px 圆角（四角补色块），色带叠一层
+  顶亮底暗的薄釉；翻色 = 同一帧换 background，帧确定
+- 产品窗口（1560×864，原生像素布局）spring(damping 15, stiffness 115)
+  从下方 660px + 前倾 18°→0 + scale 0.88→1 落进框内（帧 10 起，画框长出
+  中段），下落按速度纵向运动模糊，阴影随高度 70→22 收紧
+- 动机：光标 56–80f 弧线滑向标题栏 Design | Dev 开关，80 按下、84 松开 = 翻色帧
+- 翻色帧四件事同帧：画框换色 + 窗内布局 A→B 硬切（右栏浅色检查器→深色
+  CSS 面板、左栏图层→tokens、蓝选框→橘标注）+ 框带角标换字
+  （DESIGN→DEV MODE，右上 video-shotcraft 字标常驻，色带上用单色白版标志）+ 开关态
+- 翻色瞬间叠 3 帧径向白闪（0.6 起阶梯衰减，框带最亮）+ 画框厚度阻尼
+  弹跳（exp(-0.24t)·cos(0.95t)·12px）+ 内容 ~1% 顿挫，给"换挡"打击感；
+  余波：标注线 3f 错峰画出、数值胶囊过冲弹出
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 画框厚度 | 60px（1080p），角标 30px 粗体全大写 | 太薄读作描边、角标也放不下可读字号；>64px 开始吃内容区 |
+| 画框生长 | 19f snappy，先于窗口 10f | 画框必须先立——内容先到画框后包读作补救 |
+| 窗口落位 | spring(damping 15, stiffness 115)，y 660→0 + rotateX 18°→0 + scale 0.88→1 | 落进"框内"是语义关键，落点必须完全在框带内侧 |
+| 翻色时刻 | demo 84f（光标松开帧）；停一拍（窗口落定后 ≥30f）再翻 | 落定没坐稳就翻，观众还没建立"蓝=当前模式"的编码 |
+| 白闪脉冲 | 3f，0.6→0.2 阶梯，径向（框带处最亮） | 帮眼睛登记"这一帧变了"；>4f 读作底色频闪，抢了翻色的戏 |
+| 厚度弹跳 | exp 衰减 cos，初幅 12px | 纯硬切略干；弹跳是"挡位卡进去"的机械回馈 |
+
+## 已知坑
+- demo 用手搓的设计工具窗口调校通过（框带角标是 video-shotcraft 标志 + 字标，画布上是一张 video-shotcraft 推广卡）——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 翻色必须真同帧：画框、窗内布局、角标文字三者错开哪怕 2f，"换挡"就散成三个小动画
+- 颜色编码要全片守约：蓝框段落里不许出现绿色主 UI 元素，编码被稀释后翻色就只是换色
+- 画框是包装层不是主角：全片翻色 ≤2 次，翻多了读作霓虹灯（P4 克制原则）
+- 两个模式的品牌色对比度要够（demo 钴蓝 #2F55FF / 橘红 #FF5B1F，色相对冲 + 明度差）；同明度邻近色翻了等于没翻
+- 窗内 UI 保持中性墨色，强调色只跟模式走（蓝段的选中态是蓝、橘段的标注是橘），否则编码被 UI 自身颜色稀释
+- 声音：翻色帧钉一声干脆的机械 click/换挡声，白闪与声同帧；画框生长段可静
+
+## 参考实现
+demos/effects/brand-frame-snap/
+（BrandFrameSnap.tsx）
+原片出处：figma-devmode 0:28–0:32 + 0:43–0:47

package/lib/motion/shotcraft/upstream/references/shots/effects/fui-hud-moves.md

@@ -0,0 +1,35 @@
+---
+name: fui-hud-moves
+一句话: FUI/HUD 准星咬合——reticle-lock-on 四个 L 形角标组成的取景框从画外飞入、超调回弹后咬合锁定目标
+适用: 任何"看这里"的目标点名（替代箭头圈红，画面不冻结）
+时长: 2–3s（demo 90f）
+能量: 中高（咬合帧是打击点）
+标签: ui-entrance
+---
+
+## 意图
+科幻虚构界面（Jarvis/Territory）里可中性化的母题：运动中的捕获。
+四个 L 形角标从画外冲入、超调回弹、"咔"地咬合到目标元素四角+弹标签
+——与 freeze-annotate 分工：那卡冻结画面标注，本卡在流动中点名。
+
+## 式
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A reticle-lock-on | 四 L 角=同一对矩形四份镜像，飞入（10f out cubic）与收缩（2.2×→0.94×→1 超调回弹）解耦；咬合帧目标微亮+标签 back 弹出 | 目标点名；踩音效重拍 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 飞入行程 | 画外 ≥1000px 冲入 | 行程短读作"角标出现"不是"扑过来" |
+| 超调 | 收缩过头到 0.94× 再回弹 1 | 无超调没有"咔"的咬合感 |
+| 咬合帧 | 目标白 overlay 快闪 0.55→停 0.28 + 标签同帧弹出 | 微亮与标签错帧就散了 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 一支片 ≤2 次：连用读作军事模板；两次锁定目标必须不同
+- 声音：咬合帧一声"咔"（机械 click 而非游戏 UI 音，S1 边界内）
+
+## 参考实现
+demos/effects/fui-hud-moves/
+（ReticleLockOn.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/glow-flyline-moves.md

@@ -0,0 +1,53 @@
+---
+name: glow-flyline-moves
+一句话: 暗场光斑与飞线三式——glow-orb-ambient 光斑底噪、flyline-arc 飞线连接、orb-flyline-relay 同帧共振组合
+适用: 全片唯一暗场段落的氛围与数据叙事：铺底噪用 A、讲数据流向用 B、要背景给前景搭腔用 C；Linear 官网味
+时长: A 170f（~5.7s）/ B 140f（~4.7s）/ C 165f（5.5s）
+能量: A 低（底噪级）/ B 中 / C 中高
+标签: data
+---
+
+## 意图
+这是库内第一张整卡住在**暗场**的卡。白底提亮不可见判例反过来读就是：
+要玩光，先去暗场。A 是空间的呼吸——深色底三团大光斑有机漂移，从中央
+磨砂玻璃卡背后游过、颜色透过玻璃染进卡面，卡缘随最近光斑靠近而泛光，
+背景不再是死的；B 是数据的动词——发光弧线从 A 卡"打"到 B 卡，
+亮点头领跑、渐隐光尾，落点描边脉冲点亮，指标关联第一次有了方向；C 是 A+B 的焊接——飞线落点帧邻近光斑同帧涨亮一拍，
+氛围层与事件层**同帧共振**，互相搭腔而非各演各的（组合命门：拆开共振帧
+就退化成两张卡并置）。
+
+## 三式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A glow-orb-ambient | 三团 760–1200px 多段径向渐变光斑（screen 叠加，不做实时 blur），双正弦漂移；中央 1100×600 磨砂玻璃卡（backdrop 模糊 + 提饱和）让光斑透色；卡缘辉光按光斑距离 [240,760]px→[1,0] 加权取 max 驱动 + 朝主导光斑的定向轮廓光 | 暗场段落铺底；卡呼吸感 |
+| B flyline-arc | 暗场 dashboard 压暗当底，卡心到卡心的手写 bezier 100 段采样，22f out-cubic 生长；光头 + 彗尾条件挂载领跑，段 opacity 按离头距离渐隐、到站 10f 抹匀；起点锚亮起、落点节点常驻；落点卡描边脉冲 + 冲击环，可接力 | 数据流向/指标关联；dashboard 叙事 |
+| C orb-flyline-relay | A+B 焊接：三颗玻璃节点各配一团背后光斑，光斑 surge 与节点点亮共用落点帧常量，涨亮 1+1.6×surge 并放大 12%、5f 起升 15f 消散；飞线到站后消散成细点虚线 | 暗场高光段；三站接力收束 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 光斑 | 潮青 / 深海蓝 / 珊瑚，峰值 0.55/0.5/0.42；漂移振幅 280–300px、周期 96–150f 交叉不等 | 同周期漂移读作整体晃动不是"有机" |
+| A 玻璃卡 | backdrop blur 44px + saturate 1.5；祖先不能带 filter / opacity<1 | 祖先成为 backdrop root 时玻璃里看不到光斑（入场淡入放在玻璃层自身） |
+| A 卡缘辉光 | box-shadow 0→90px 主导光斑色 0.32 + 1.5px 定向渐变轮廓光 | 无辉光光斑与卡互不认识 |
+| A 收敛 | 115–145f out-sine 收敛冻结（振幅 60/π，起始斜率 = 1 速度连续），末 25f 真静止 | 硬停一帧读作卡死；缓动收敛才有真静止 |
+| B 线体 | 暗场版（demo）：白芯 3.5px butt 分段 + 7px/18px 两层靛蓝辉光；浅底版：白线 4.5px + 9px 深色衬底 | 浅底无衬底白线直接消失（判例）；分段用圆头会在渐隐尾叠出珠串 |
+| B 光头 | 白点 r7 + r40 halo + 9 点彗尾，仅生长期条件挂载 | opacity 到 0 不算摘罩，永不真静止 |
+| B 脉冲 | 描边扩散 out-cubic 6f / 消散 12f 到残余 0.25；暗场版提亮（强调色描边 + 外辉光 + 极淡卡面提亮）+ 14f 冲击环；f86 后全静止 | 白底禁提亮——浅底版用加深罩 0.16 替代 |
+| C 共振 | 落点帧同帧起 surge（同一常量 LIT_B / LIT_C）；节点 8f 亮到 1 + 描边脉冲残余 0.35 + 20f 冲击环 | 错 2f 以上共振读不出"搭腔" |
+| C 时间轴 | 动作 f98 前结束、光斑 110–140f 收敛冻结，末 25f 真静止 | 氛围层最后冻，事件层先收 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 暗场段与纸墨浅底主视觉切换成本高——全片暗场段 ≤1 段，进出
+  用 shot-transitions 藏切族垫，别生切明暗
+- 光斑漂移末段**必须**缓动收敛到静止再冻结——匀速漂移直接 clamp
+  是一次可见的急刹（A 式 out-sine 收敛判例）
+- 实战品牌色版：光斑用品牌色对（如蓝紫），灰阶参数只保证明度关系，
+  色相对比要重调
+- B 接力线 ≥3 条时改用 C——纯飞线连打读作大屏模板，共振才有作者感
+- 声音：B/C 每次落点一声轻打点，A 无声（sound-design §4.5）
+
+## 参考实现
+demos/effects/glow-flyline-moves/
+（FlylineArc.tsx / GlowOrbAmbient.tsx / OrbFlylineRelay.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/icon-performance-moves.md

@@ -0,0 +1,42 @@
+---
+name: icon-performance-moves
+一句话: 图标表演——attention-bounce 求关注弹跳（图标连跳递增+落地压扁+镜头被吸引）
+适用: 半屏级 icon 特写段落；新功能引出
+时长: 156f（5.2s）
+能量: 蓄势引入
+标签: interaction
+---
+
+## 意图
+库内图标动画品类首批入库：icon 是镜头怼着拍的表演者，不是 UI 角落的
+微交互。attention-bounce 是 macOS Dock 语汇——Dock 里的 video-shotcraft
+app 图标原地连跳 4 次一次比一次高（0.35→1.2 倍 icon 高），每次落地压扁
+（末跳宽 1.2x 高 0.8x）+涟漪溅点，邻居图标逐渐失焦、跳最高那下镜头向它
+轻推 8%（被吸引），落定后弹开「New in Shotcraft」功能面板——把"用户注意力"
+剪进叙事。
+
+## 做法
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A attention-bounce | 抛体弹跳（时长 ∝ √高度）递增 + 空中速度拉伸 + 落地 2f 挤压 + 涟漪溅点，邻居 rack focus 失焦，峰值跳镜头 scale 1.08 推近，落定触发角标 + 面板弹簧展开 | 新功能引出："看我"→镜头看它→它开面板 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| icon 尺寸 | 360–400px 高（半屏特写；demo 图标 360） | 角落小图标做表演没人看见——表演者必须占 C 位 |
+| 递增弹跳 | 4 跳 0.35→0.6→0.85→1.2 倍 icon 高，空中 14/18/22/26f（∝ √高度） | 等高连跳读作 loading；递增才是"越喊越大声"；时长不随高度变读作失重 |
+| 落地挤压 | 接触 2f，压扁量 0.1→0.2 递增（末跳宽 1.2x 高 0.8x），末跳阻尼余弦回稳 | squash 缺席=没有重量 |
+| 镜头推近 | 末跳 72–90f smooth 推 8%；邻居 30–96f 失焦到 7px、降饱和 30% | 镜头动作把"被吸引"的观众视角演出来 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 同批 bell-swing-alert（铃铛甩摆）淘汰无附言——挂点摆动型 icon
+  表演相性存疑，做新 icon 表演优先弹跳/爆发型
+- 首版曾出画框（末跳最高点顶出），弹跳高度与画面上留白先算像素
+  （demo：地面 960、图标 360、末跳顶点 168px，推近 8% 后约 119px）
+- 声音：每次落地一声"duk"音调递升，面板弹出一声轻"叮"
+
+## 参考实现
+demos/effects/icon-performance-moves/
+（AttentionBounce.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/impact-feedback.md

@@ -0,0 +1,50 @@
+---
+name: impact-feedback
+一句话: 命中反馈两式——hit-counter 连招计数（顿帧+伤害数字+combo 跳字）、anime-impact 动漫打击帧（负片+集中线+色散）
+适用: 元素落位/撞击的"命中一瞬"——给砸入、撞停加游戏级手感；按强度阶梯选式
+时长: n/a（元素级技法，寄生在落位动作上；各式占用帧数见参数表）
+能量: 高（瞬时冲击）
+---
+
+## 意图
+元素砸到位却没有"砸到了"的一瞬，落位读作 PPT 飞入。游戏 juice
+（Vlambeer screenshake 理论）与动漫演出 impact frames 给了同一答案：
+命中的那几帧把时间咬住，冲量才传到观众手上。两式是一条强度阶梯：
+B 用局部顿帧叠伤害数字和 combo 跳字，把功能清单剪成一套连招，
+叙事感最强；C 是最重的一拳——撞停 3 帧翻负片炸集中线，强调级最高、
+最风格化。
+
+## 两式选型表
+| 式 | 做法 | 适用 |
+|----|------|------|
+| B hit-counter 连招计数 | 三卡接连砸入，每命中 = 顿帧 2f + 伤害数字上浮 + ×N 计数跳字逐次加码；demo 把"伤害"写成 video-shotcraft 每项功能省下的制作时间，飘走后落进卡片页脚 | 功能点连打段——"功能很多"用连招讲；游戏化语言浓 |
+| C anime-impact 打击帧 | crash-zoom 撞停的 3f 整幅负片反色 + 放射集中线 + 红青色散，第 4f 全撤 | 全片唯一高潮的那一拳；强调级封顶 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| B 节奏 | 三卡各隔 28f（动画时间 30/58/86），命中前 10f ease-in(quad) 砸落；每命中全局冻结 2f（背景斜纹滚动也一起冻） | 间隔均匀才有"连招"节拍感 |
+| B 伤害数字 | 打在卡面中下部，scale 1.45→1 + 上浮 150px 出卡沿，4f 后 12f 渐隐；字号逐击 88/104/124px，黄色斜体 + 硬投影 | 渐隐 >16f 拖泥带水，遮住下一击；从卡顶上方起跳会撞上角落计数器 |
+| B 计数器 | 脉冲峰值 1.3/1.45/1.6、rotate −2/−4/−6°、字号 140/166/196px，`exp(−t/2.4)` 回落；三格热度条逐格点亮 | 逐次加码是命门——三次一样大读不出"越打越狠" |
+| C 急推撞停 | 先 6f 预备回拉到 0.985，再 crash-zoom 6f ease-in(cubic) 推到 2.25x（卡高 454×2.25≈画高 95%，描边不被画框切半），卡心收敛到画面正中；飞行帧做时间采样运动模糊 + 中心锐利副本 | 急推参数走 crash-zoom-punch 卡 |
+| C 冲击帧 | 撞停起 3f：`invert(1) grayscale(1) contrast(1.45)` + 34 粗楔 + 22 细针集中线（每帧换形态，内端被径向渐隐吃掉留出焦点）+ 红/青负片副本 screen 叠加 ±8px 错位；第 4f 全撤，卡外页面压暗一拍 | 3f 是甜点——4f 起观众开始"看清"负片，魔术就穿帮 |
+| C 恢复震屏 | 第 4f 起 6px 指数衰减（τ≈2.2f），~12f 收干 | 幅度须过肉眼阈值（可感性判例） |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- B 式顿帧**必须全局**——背景滚动也要一起冻，否则读不出"时间被
+  咬住"，只像那张卡掉帧。demo 用统一 remap 帧 df 驱动所有层是命门；
+  唯闪白等"冻结期间也要发生"的效果用真实帧 f 驱动
+- 帧 remap 与 speed-ramp-freeze 同技术根，同一镜头别叠用两卡——
+  两套 remap 互相打架，节奏读作故障
+- C 式负片帧在纸墨审美的片子里非常抢戏——限高潮一次，且必须与
+  impact 音效同帧落地（拟音走 sound-design），无声的负片帧读作闪坏
+- B 式游戏化语言浓（伤害数字/combo 是明晃晃的游戏梗），产品调性
+  偏严肃时慎用
+- B 式多次顿帧后真实帧比动画时间多出累计冻结帧，排镜头预算时
+  按 `真实命中帧 = 动画命中帧 + 已冻结帧数` 折算（demo HITS_REAL）
+
+## 参考实现
+demos/effects/impact-feedback/
+（AnimeImpact.tsx / HitCounter.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/light-play-moves.md

@@ -0,0 +1,46 @@
+---
+name: light-play-moves
+一句话: 光效两式——spotlight-sweep 聚光扫字、sheen 单点扫光
+适用: 把光当另一种笔触（扫/擦）：暗场标题揭示（A）、主角卡加冕（B）
+时长: A 170f ~5.7s / B 150f ~5s
+能量: A 中 / B 低
+标签: typography
+---
+
+## 意图
+库内"光"一直只有 spotlight-hero-card 一个点射手法；这两式把光做成
+体系，两种笔触两种职责：A 是**扫**——暗场里几乎不可见的标题被锥形
+光摆动扫亮，光到哪哪亮，与 spotlight-hero-card 的区别是那个打卡片、
+这个扫文字；B 是**擦**——深墨主角卡上一道 45° 高光带缓扫一次，被
+圆角裁住，无声的加冕。
+全部深底或深主角——**白底上提亮不可见**（判例）是这整张卡的地基。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A spotlight-sweep | 双层同文本：暗版 0.07 常驻，亮版 radial mask 随光斑走，钟摆式追光摆两个半来回阻尼停在正中，iris 张开全亮定格（demo 标题「Craft the shot.」，收在 video-shotcraft 字标） | 暗场大标题揭示开场 |
+| B sheen-sweep | 深墨卡（demo：钛黑金属卡，蚀刻 video-shotcraft 单色标志与字标）转向光源的同时，115° 高光带扫一次，overflow hidden 圆角裁剪 | 主角卡静止段的一次加冕 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 反差 | 暗版 0.07 vs 全亮 1.0；demo 为暖白 #f8efe2 衬线字对酒红黑天鹅绒幕布（#1a0a0d→#070203），幕布本身也只在光斑里被照亮 | 反差是本式全部；暗版 >0.15 就没有"点亮"了 |
+| A 光斑 | ellipse 360px（硬芯+长软边），钟摆：x = 960+600·sin θ·env，θ 从 −π/2（最左）起、周期 50f、走 2.25 个周期至 f121；y 走下凹弧（中心最低 44px）；env 第一来回后 smooth 收到 0，x 与速度在 f121 同时归零（纯 sin 会在中心最快时急刹）；开灯 4–10f 钨丝预热闪两下 | f121–141 iris 张开 360→1080px 全亮（out-cubic）、光锥线性收成柔和顶光（扩散/消散解耦判例） |
+| B 高光带 | 宽 2×卡宽，115° 渐变：宽柔光 0.14 + 窄亮芯 0.5（暖白，screen），58–90f swift 扫一次；同段卡 rotateY 21°→14°（转向光源 = 扫光的物理动机）；光带下拉丝纹与蚀刻字的亮版副本被同一遮罩揭开 | 0.5 芯在钛黑上足够响又不糊；双向 clamp + 条件挂载保证只扫一次 |
+| 摘罩 | 扫光（B）条件挂载，扫完即卸载；A 光锥收成常驻柔和顶光 | opacity 0 残留层照样每帧合成——不用的光效层直接卸载 |
+| 收尾 | A ~30f / B ~55f hold；hold 段只留极缓运动（A 浮尘与顶光呼吸、B 卡 rotateY 再转 1.5°） | 不加手持抖动（Q3） |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- **全片光效合计 ≤2 次**——光是最快掉价的手法，每个卡都闪一下
+  等于廉价模板
+- B 式是高标准重试通过：旧否决（2026-07-13 判例）针对当时实现不好看，
+  非路径不可行；四约束 = 单点+主角+圆角裁剪+只扫一次，违反任何
+  一条回到否决区
+- 深底是地基：两式全部依赖深底/深主角，白底上做光效直接跳过本卡
+- A 与 spotlight-hero-card 同片二选一，都是"聚光"语汇
+
+## 参考实现
+demos/effects/light-play-moves/
+（SheenSweepRetry.tsx / SpotlightSweepReveal.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/radial-ripple-phone-chips.md

@@ -0,0 +1,56 @@
+---
+name: radial-ripple-phone-chips
+一句话: 暖沙底四层同心圆错相呼吸如水波，中央手机 mockup 屏内 feed 自动缓滚，两侧白色 chip 先后 spring pop 入场并悬浮
+适用: 移动端产品的"这就是它"定格镜头；功能点分列两侧的介绍段；片头/片尾的产品全景
+时长: 约5.6s（168f@30fps）
+能量: 低（安静、有呼吸感，靠同心圆的持续起伏撑住不冷场）
+---
+
+## 意图
+用最少的动作把手机放在画面正中并让它"活着"：同心圆负责氛围呼吸，
+屏内自动滚屏负责证明"里面有内容在跑"，两侧 chip 负责点出功能名。
+三层动作各自极慢，叠起来才不会显得静止——这是产品定格镜头的标准配法。
+
+## 动效核心
+- demo 画面（look = sand，手机里是 video-shotcraft 的镜头库 feed）：1080p 原生尺寸布局（不走 DesignStage 放大），
+  手机 430×900 占画高 83%，左下角镜刻标志 + video-shotcraft 字标在两枚 chip 落定后升起，收尾是一张产品海报
+- 4 层同心圆（2240/1760/1280/840px，#dccbb4→#f2eadf 由深到浅，最外两层出画铺满）各自
+  `scale 1 ± 0.06`，全片走 1.5 个正弦周期，相邻层相位差 1.7 rad
+  ——错相是"水波"而不是"整体缩放"的关键；每层带受光上沿 + 白色发丝外缘，中心一团暖白柔光托住手机
+- 手机：暖钛金属边框 12px + 黑边 9px、70px 圆角、灵动岛/侧键/玻璃斜反光，两层落地投影；
+  0–26f 从下方 90px snappy 升起，投影随落位收紧
+- 屏内为镜头设计的 feed：大标题 + 精选大卡 + 8 条单集卡（几何插画封面 / 标题 / 时长·节目 / 收听进度），
+  底部常驻迷你播放条（进度匀速推进、波形确定性轻跳），状态栏与播放条下方各一层屏幕底色渐隐
+- feed `translateY 0→−560px`，窗口 `t 0.08→0.98` **匀速无缓动**
+- chip pop：`springAt(t0, damping 13, stiffness 190)` 驱动 scale 0.8→1（一次可见过冲），
+  同时从手机一侧 snappy 外移 28px、opacity 5f 跳满；左 chip 起 37f、右 chip 起 67f
+- pop 完接 `sin` 悬浮 ±8px（2 周期/全片），并由 pop 后 18f 起 24f 的 smooth 渐渐介入
+  ——不是一落位就开始飘
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 同心圆层数/尺寸 | 4 层 2240/1760/1280/840px（1080p） | 3 层撑不满画面；最外层要出画，否则读作一块圆形色板 |
+| 呼吸幅度 | scale 1±0.06，1.5 周期/全片 | 0.06 已是上限；到 0.1 就读作"脉冲动画"而非水波 |
+| 相位差 | 相邻层 1.7 rad | 相位全同 = 整块放大缩小；差 1.7 才有波从中心荡开的错觉 |
+| 手机投影 | 贴近实影 0 4px 10px + 远影 0 40px 80px -20px + 环境影 0 90px 140px -40px（sand.shadow 带色相） | 投影是手机"浮在波上"的唯一依据，去掉就贴平了 |
+| 自动滚屏 | translateY 0→−560px，t 0.08→0.98 匀速 | 加 ease 立刻读作"有人在滑"；匀速才是自动播放 |
+| chip pop | spring damping 13 / stiffness 190，scale 0.8→1，外移 28px | 过冲量是"弹出"的全部质感，damping >20 就平了 |
+| chip 时序 | 左 37f / 右 67f（1s 差） | 同时出现读作两个标签；错开才有"一个一个说"的节奏 |
+| chip 悬浮 | ±8px、2 周期，pop 后 18f 起 24f 渐入 | 幅度超过 ~12px 就和同心圆的呼吸抢戏 |
+| chip 字号 | 36px / 600 字重 + 60px 强调色图标圆 | 1080p 下 chip 是要读的字，别回到 12–20px 的贴纸尺寸 |
+
+## 已知坑
+- chip 用 `right: 1920 − PX + CHIP_GAP` / `left: PX + PW + CHIP_GAP` 贴着手机外缘定位；
+  改手机宽度 PW 后两侧 chip 自动跟随，但要确认长文案 chip 的外缘仍在 96px 安全边距内
+- 屏内 feed 是假条目的占位内容，落地换真实截图时总高必须
+  大于「560px + 屏高」，否则滚到底露白
+- 手机屏只有 ~390px 宽：单集卡标题控制在 ~18 个字符、元信息 `nowrap + ellipsis`，否则折行把卡片撑高
+- 同心圆是实色叠放（不是描边圆环），层序必须由大到小 append，
+  顺序反了就只看得见最大那层
+- ACCENT（默认 sand 的赤陶 #c4552d）作用于屏内封面/进度条/播放键与 chip 图标，
+  换项目品牌色只改这一个变量即可换肤
+
+## 参考实现
+demos/effects/radial-ripple-phone-chips/
+（RadialRipplePhoneChips.tsx）