dsh-drawai 0.3.4 → 0.4.0

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/element-body-moves.md

@@ -0,0 +1,37 @@
+---
+name: element-body-moves
+一句话: 元素身体感——contact-shadow-lift 接触阴影离面抬升：卡抬起时桌上的阴影同步放大变淡，纸片离桌被阴影证明
+适用: 给"位置在变"之外补"身体在变"：卡片点名给悬浮证据；配 2.5D 运镜与逐张点名
+时长: A 150f 5s
+能量: A 低中
+---
+
+## 意图
+库内运动卡全在管"位置在变"——飞入、滑动、弹跳，元素本身始终是刚体。
+这一式管**身体在变**：给悬浮一个可信的证据——卡抬起时正下方阴影同步放大变淡，
+纸片离桌，staging 法则给 2.5D 运镜垫的物理台词。与 CameraMotionBlur 的区别：
+快门拖影是相机的事，离面抬升是身体的事。
+
+## 选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A contact-shadow-lift | 斜俯拍桌面（rotateX 24°→20°）上卡沿法线 translateZ 96px + scale 1.05；阴影是躺在桌面 z=0 的两层独立实体（接触核 + 环境影），随抬升变大、变虚、变淡、向背光侧偏移；点名卡落回 8f in-cubic + 2f 微压卡壳，末张选定卡弹簧抬起后停在空中 | 逐张点名强调；2.5D 段落的离面铺垫 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 抬升幅度 | 2D：−28px + scale 1.08；2.5D 斜俯拍：translateZ 96px + scale 1.05（屏幕可见位移 40–50px） | 判例锁死：屏幕可见位移 <12px 禁用（见已知坑） |
+| A 阴影 | 独立 div（2D 用椭圆径向渐变；2.5D 用与卡同形的圆角矩形 + blur）：接触核 α 0.32→0.14、blur 3→25px；环境影 α 0.09→0.22、blur 14→54px、向右下偏移；卡本体不带外阴影 | box-shadow 跟卡走，给不出"影子留在桌上" |
+| A 落地 | scale 0.99 卡壳 2f 再 5f 回弹到 1 | 无微压读作飘落，没有重量 |
+| 收尾 | 末张选定后悬停 ~50f | 若要循环，把末张改成同样落回 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- A 微幅加码判例：原案 8px 抬升不可感，加码到 28px 才过——实战禁回调到 12px 以下，宁可不用不可用弱
+- A 一次只抬一张——两张同时离桌，观众找不到被点名的是谁（P4）
+- 声音：抬起轻吸/落回轻放（sound-design §4.5）
+
+## 参考实现
+demos/ui-entrance/element-body-moves/
+（ContactShadowLift.tsx：porcelain 斜俯拍桌面上三张 video-shotcraft 镜头配方卡「Pick your shot.」，扫—扫—选，选定卡是带标志的 Logo sting）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/integration-hub-map.md

@@ -0,0 +1,55 @@
+---
+name: integration-hub-map
+一句话: 旧页面一次性快翻 180°（侧棱瞬间亮闪）落成新中枢页，五个集成 app 图标同帧弹现、随即五条彩虹光管同帧齐连，光管内输送脉冲持续流动——"翻开新一页，生态一齐接入"
+适用: 集成/生态能力段（一个产品连一切）；版本翻新叙事（旧页翻成新页）；暗场霓虹调性的功能高潮
+时长: 前摇 ~0.5s + 快翻 ~1.2s + 图标齐现 → 光管齐连两拍 ~0.7s + 输送呼吸 ≥1.5s；全段 4.5–5s
+能量: 中高（翻面是爆点，输送段是余韵）
+标签: effects
+---
+
+## 意图
+翻面是"换时代"：旧文档页整个翻转 180° 得到新中枢页——必须是
+完整翻面不是转个角度（判例），翻的动作**快翻+尾段减速**、一口气
+完成无分段停顿（"匀速"判例：用户说的匀速=无停顿，不是字面
+linear；90° 侧棱停顿版被裁）。侧棱时刻只"闪一下"（1–3f 脉冲，
+长光晕平台被裁）。接入是**两拍制**：五图标同帧弹现（第一拍）→
+五管同帧起画齐连（第二拍）——齐，才读作"生态一次到位"；错峰
+逐个连读作逐个谈判（两轮被裁）。连通后光管内亮脉冲沿图标→中枢
+方向持续循环，"输送感"是终态的生命。
+
+## 动效核心
+- 翻面：rotateY 0→180°，35f，Easing.out(cubic)（前 41% 时间完成
+  80% 角度，尾段长减速缓着陆），双面卡（正面旧页/背面新页）
+- 侧棱瞬闪：~90° 时刻 2f 脉冲 bloom（0→1→0.25→0，4f 内归零）
+- 两拍制接入：五图标 tIcon 同帧（翻面落定 +3f）弹现；+10f 五管
+  tPipe 同帧起画，9f 齐长全亮
+- 输送脉冲：光管 dash 亮斑沿图标→中枢方向循环（速度 ~4.6px/f，
+  各管相位错开），全连通后中枢页轻呼吸
+- 背景：暗紫底噪 + 霓虹矩形浮现衬场
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 翻面时长 | 35f（曾 70f 被裁"再快1倍"） | <24f 读不出双面；尾段减速比例 ~60% 时间走 20% 角度 |
+| 翻面曲线 | ease-out 单调无停顿 | 侧棱停顿/分段被裁；严格 linear 起停生硬也被裁——快翻尾缓 |
+| 侧棱闪 | 2f 脉冲、4f 归零 | 长光晕平台被裁"闪一下就行" |
+| 接入节奏 | 两拍制：图标同帧 → +10f 光管同帧 | 错峰逐连两轮被裁"同时出现，然后同时连接"；两拍间隔 <6f 读作一拍 |
+| 光管生长 | 9f 齐长 | 18f 版偏慢；各管长度不同但同帧到达（按各自 len 归一） |
+| 输送脉冲 | ~4.6px/f 循环、相位错开 | 静态连线=没有"输送的感觉"（判例）；同相位读作闪烁 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 时序判例链完整记录在案：错峰连入 ×2 被裁 → 管齐图标错峰被裁 →
+  两拍制过关。"同时"是这张卡的节奏身份
+- 与 glow-flyline-moves 分工：那张是飞线本身的光效戏；本卡是
+  翻面+两拍接入+输送的叙事结构，光管只是元素
+- 与 canvas-materialize-moves 分工：那张是画布元素实体化；本卡
+  核心是"旧页翻成新页"的换代语义
+- 双面卡实现：水平/垂直线 bbox=0 会使 SVG filter/渐变失效（三管
+  消失判例），管线渐变用 userSpaceOnUse 每管独立定义
+
+## 参考实现
+demos/ui-entrance/integration-hub-map/
+（IntegrationHubMap.tsx）
+原片出处：clickup-30.mp4

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/list-reveal.md

@@ -0,0 +1,50 @@
+---
+name: list-reveal
+一句话: 垂直菜单 6 项按 10f 的间隔依次 scale 找位、软 back 轻微过冲落定，同时整个列表容器全程匀速上移——逐项入场与整体漂移是两层不相干的运动
+适用: 导航/侧边栏/设置面板的入场；任何"界面自己长出来"的 UI 段落，也适合做旁白铺垫时的低能量底
+时长: 约 4s（120f@30fps）
+能量: 低（稳定节拍，无峰值；靠漂移维持画面不死）
+---
+
+## 意图
+列表逐项淡入是最容易做得死板的一类动效：每项动完就停，画面在两项之间是完全静止的。
+这张卡的解法是给容器加一层与逐项入场无关的慢速漂移——局部在"找位"，整体在"呼吸"。
+观众读得清每一项，同时画面从头到尾没有一帧是钉死的。
+
+## 动效核心
+- 两层运动完全解耦：容器 `translateY(DRIFT/2 − DRIFT·f/(N−1))` 只吃全局帧，是贯穿全片的匀速漂移
+  （demo：1920 坐标下总 96px，+48 → −48，≈0.8px/f）；每项只吃自己的局部窗口，互不参与对方的计算
+- 逐项入场：起点 `2 + i·10f`、窗口 24f，stagger 10f 比常规 UI stagger 慢一档——这是"读得完"的间隔，
+  不是"快速铺开"的间隔；窗口是 stagger 的 2.4 倍 → 相邻 2–3 项同时在动，队列连绵
+- 找位动作是 scale 主导：`scale(0.82 → 1)` 配 `translateY(44 → 0)` + 对焦模糊 8px → 0，
+  观众感知到的是"从虚到实、从小长到位"，而不是"从下面飞上来"
+- 软过冲 `bezier(0.3, 1.18, 0.5, 1)`（~1.5%）——量很小，作用是把落位那一帧从"停"变成"扣住"
+- 跟随：图标晚 2f、右侧快捷键 / 徽章晚 4f 落定；透明度 `min(1, lin·2.2)`，行程 45% 就已全实
+- 当前项（Home）是全片唯一的高亮：瓷白实心条 + 落位后一次扫光（Q4）；其余项为深石墨面 + 发丝线
+
+## 参数表（demo 为 1920×1080 原生坐标）
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 项数 | 6（Home…Sign out） | 末项 52f 起、76f 落定，尾部留 ~44f 给观众收尾；>8 项必须压 stagger，否则末项吃到收尾 |
+| stagger | 10f/项 | 10f 是"逐项读得完"；压到 4f 变成一次铺开（另一种手法），拉到 16f 以上节拍会散 |
+| 单项窗口 | 24f | 窗口比 stagger 长 2.4 倍 → 相邻项重叠；两者相等会变成一项一项硬接 |
+| 起始 scale | 0.82 | "已经能认出是个条目"的尺度；<0.5 读作从零弹出，和 pop 类手法混淆 |
+| 起始位移 / 模糊 | 44px / 8px | 位移必须小于行距（92px 行高 + 14px 间距），否则项与项之间穿插 |
+| 过冲 | 软 back ~1.5% | 要小到几乎读不出来；换 spring 或加大过冲，6 项连续抖会显得廉价 |
+| 容器漂移 | 全程匀速 96px（≈0.8px/f） | 总量是单项位移的 2 倍、速度慢一个数量级——读作"画面在呼吸"；速度接近单项入场速度时两层运动混为一件事 |
+| 透明度斜率 | `min(1, lin·2.2)` | 降到 1 会看到半透明项叠在背景上，暗场下尤其脏 |
+
+## 已知坑
+- 容器漂移是匀速且贯穿全程，末帧停在 −48px 而不是 0——这个动效**末帧不回位**。
+  要循环播放或与后一镜对齐位置，得把漂移换成收束曲线，或在末段补一个反向缓收
+- 项数变化必须重算 stagger：末项起点 `2 + (n−1)·10f`，再加 24f 窗口，要给收尾留 ≥30f
+- 行宽 700px、标签 `nowrap`——中文或更长的英文标签会顶到右侧快捷键，换文案要同步加宽；
+  列表总高 ~644px，加项前先算漂移后首末项是否仍在安全区内（demo 漂移范围 y 188–928）
+- 漂移方向（向上）与逐项位移方向（44px→0，也是向上）同向。这是有意的（同向叠加更顺），
+  但两者速度量级必须保持一个数量级差距，否则读作"一起往上飘"而非两层
+- 右侧标题要等列表铺到一半（46f）才进：开场只给列表一个主角（Q5），不然观众在两处之间来回找
+- 图标是单色线性图标，只有当前项用实心高亮、未读徽章用点缀色；浅色界面下描边和阴影都要重调
+
+## 参考实现
+demos/ui-entrance/list-reveal/
+（ListReveal.tsx：graphite 暗场，左列表 + 右侧 120px 标题的侧边栏海报）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/list-stack-press.md

@@ -0,0 +1,43 @@
+---
+name: list-stack-press
+一句话: 列表卡从画面底部逐张飞上摞起，每张落地压弹整摞、计数器同步跳一格
+适用: feed/雷达/收件箱类"每天有新东西"的镜头；强调持续积累的资产列表
+时长: 约 3s（18–88f）
+能量: 中
+---
+
+## 意图
+"堆叠有重量"：每张新卡落上来，已落定的整摞被压下再弹回——观众从物理反馈里读出"这是实打实攒下来的东西"。计数器同步跳格把数量感钉死。
+
+## 动效核心
+- **预备拍（anticipation，借鉴迪士尼法则 2）**：首张升入前给一拍段落级预备——计数器先于首卡 4–6f 亮起归零/微缩 scale(0.96)→1，把视线引到堆叠区，再让首卡入画。只做段落级一次，不逐卡加
+- 卡从画面下方升入，交替微倾斜收平，等距节拍逐张摞起
+- 每张到场压下整摞 6px、8f 弹回（stackPress 脉冲——即法则 5 的 follow-through：新卡的动能传给整摞再缓冲耗散，这一笔就是"有重量"的来源）
+- 落地后按拖拽层级依次收尾（法则 5）：卡体先停 → 整摞弹回 → 高亮条再长出（滞后 2–4f）——三者同帧发生读作贴图切换
+- 收尾一道 glaze 扫光掠过整摞
+- 屏幕空间 DigitRoll 计数器落一张滚一格；相机跟随堆叠向下
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 节拍 | CUES=[18,30,42,54,66]（12f 等距），每张飞 22f，bezier(0.45,0.05,0.25,1.12) 末端过冲 | 少量卡（5 张）可以等距；大批量入场才需要递加速（对照 deck-deal 的 R2） |
+| 入场 | 从下方 600px 升入，交替 ±2° tilt 收平，scale 1.06→1 | 交替倾斜打破对称；同向倾斜读作复制粘贴 |
+| 堆叠压感 | 后一张到场时整摞压下 6px、8f 弹回（脉冲 [cue,cue+4,cue+8]→[0,6,0]） | 这是"有重量"的关键一笔，砍掉后堆叠变成简单排版 |
+| 阴影 | 两层 softShadow 随离地高度变化：空中 elevation≈56、落定 3（被压时更贴地）；飞行段按速度加纵向运动模糊 | 阴影随高度收敛，和 deck-deal/spotlight 同一套语言 |
+| 联动高亮 | 落地后滞后 2–4f 在项目名那一行（截图实测卡内 y156–176）长出与项目名等宽的强调色（模板片为琥珀）荧光笔底色，multiply 叠在字下（7f 长 + 5f 淡）；最后一张离切点仅 ~12f，压到 5f 长 + 4f 淡 | 高亮是次级动作（法则 5/8）：在主动作（落地压弹）之后跟进，不与之同帧抢戏；末尾元素的节拍要按剩余帧预算压缩，不能照抄前面的 |
+| glaze 扫光 | 360px 宽、rotate 14°、mixBlendMode soft-light，最后一张落定后帧 74→87 从 −500 扫到 2300，裁进每张卡的圆角内 | 扫光全镜头只此一次、扫整摞不逐卡（Q4） |
+| 计数器（digit-roll 手法） | 连续里程计位置 pos：每张卡落地让 pos 沿数字带 +1 格，单格 8f 滚定，bezier(0.25,0.8,0.25,1)；滚动量=pos·lineH 沿双份 0-9 带连续下滚 | 计数与落地不同步立刻穿帮；**单格滚动必须短于落卡间距（12f）且尾格在镜头收尾前滚定**——以 count 为 key 重挂重滚的写法每次都要从 0 滚 22f，12f 节拍下前一次永远滚不完、尾帧停在 4（PR #40 判例）；数字带双份拼接+overflow hidden+tabular-nums（不开 tabular 会横向抖） |
+| 相机 | zoom 1.35→0.86 一条连续曲线跟随堆叠向下（逐帧喂给 PageCam2D，避免分段关键帧处速度归零） | 正视机位（见已知坑），相机只做纵向跟随 |
+
+## 声音
+每张落地不逐张配长音；计数落定钉 click-camera（模板片钉在 f648）、段落切入钉 transition-soft（f623）。若逐张配 pop 参照 S2 三招防机枪。
+
+## 已知坑
+- 堆叠/列表信息镜头必须正视（Q6）——全片倾斜化时本镜头曾被单独回滚回正视；风格化机位逐镜头验证，不全局套用
+- 逐卡 glint 高亮扫过被否两次（Q4），高亮用静态强调色底色条即可，动感交给压弹
+- 与 history-list-stack（document-typewriter-reveal 卡尾段）是同一动作词汇——全片同一手法只当一次主角（P4），两处并用时一处必须降为配角
+- anticipation/拖拽层级参数借鉴自迪士尼 12 法则（pixel2motion skill 内置提炼版），非用户判例——是默认建议不是令；与判例冲突时判例优先
+- 预备动作幅度必须过肉眼阈值（deck-deal 判例 2026-07-09：小幅度用户完全无感，放大 12 倍才通过）——渲染后自查"不逐帧能否看出蓄力"
+
+## 参考实现
+demos/ui-entrance/list-stack-press/ListStackPress.tsx（原 template/src/aifl/live/ScenePapers.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/neon-frame-forerun.md

@@ -0,0 +1,55 @@
+---
+name: neon-frame-forerun
+一句话: 强透视直角霓虹框自左缘两头奔画先行成型，页面在框内由暗转亮，同时框内组件/文字从 3D 上空带同形软影错峰贴落、随页面点亮同步完成贴合，背景霓虹群（demo 为同形框纵深回声隧道）终段熄灭让位
+适用: 暗场品牌片里给 UI 面板做"登场仪式"（框先到、内容后落）；功能区首次亮相；霓虹/赛博调性的段落开场
+时长: 框奔画 ~0.7s + 点亮&贴落 ~2.7s + 背景熄灭收束 ~1s；全段 4–4.7s（demo 140f）
+能量: 中高（三层动作叠进，但都服务同一次登场）
+标签: effects
+---
+
+## 意图
+先立框后填肉：霓虹线框像跑道灯一样两头奔画圈出位置，宣告
+"这里要出现东西"；页面在框内由暗转亮的同时，组件从空中带影
+贴落——观众看见界面被"安放"进框里。三层动作（框奔画/页面点亮/
+组件贴落）必须**同步咬合**：贴落进程与点亮进程同步推进、稍滞后
+收尾，框光最终并入面板辉光。背景霓虹管群终段熄灭，把亮度让给
+主角完成收束。
+
+## 动效核心
+- 霓虹框：强透视直角框，自左缘中点两颗白热亮头上下分头奔画（20f，swift 起步快、
+  在右缘中点制动相撞并闪一下）；灯管用四层描边叠辉光（宽软晕 / 中晕 / 色芯 / 白热芯），
+  不用模糊滤镜，便宜且锐；成型后芯线退成发丝、框光并入面板 rim 辉光
+- 页面点亮：框合拢后页面才从黑里浮出（16–30f），再由暗转亮（24–84f smooth），
+  同时一层冷紫暗罩自左缘向右退去，读作"霓虹把页面点亮"
+- 组件贴落：**真 3D 悬空**——面板与组件都在 preserve-3d 里，组件 translateZ 120–170px，
+  面板上落同形剪影软影（越高越大越虚越淡、偏向右下）；亮度用叶子节点 brightness，
+  不在 3D 父级上加 filter/opacity（会把 3D 压平）。每件 24f 加速下落 + 软着陆，
+  落点 54→104f 按"侧栏自上而下 → 主区自上而下"错峰（先密后疏），比点亮晚 ~20f 收尾
+- 背景：同一个框在纵深里的 5 层回声（translateZ 递退、逐层放大）组成霓虹隧道，
+  框合拢后由近到远逐层"打火"（荧光管启辉的确定性闪烁）；终段中段先熄、两端后熄（94–118f）
+- 机位：rotateY −30° → −12°（0–96f EASE.out 长减速），hold 段再极缓转 1.5°
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 框奔画 | 20f 两头对奔（swift） | 单头描画读作画图；>30f 观众等不及内容 |
+| 悬浮高度 | translateZ 120–170px、影随高度收敛 | 判例：高度过小+启动过早=影子不可感（v3 第 1 轮返工加大 1.7x 并延后） |
+| 贴落窗口 | 每件 24f；落点 54→104f，比点亮晚 ~20f 收尾 | 贴落先于点亮完＝黑屋子里落家具；滞后太多读作两段戏 |
+| 错峰 | 错开起点、下落重叠并行（EASE.out 分布，先密后疏） | 串行等待被裁（掉落节奏通用判例） |
+| 背景熄灭 | 中亮尾熄，每层 6f 闪烁熄灭、层间隔 7f | 不熄灭主角不突出；同帧全熄读作断电 |
+| 贴落粒度 | 卡/行级（品牌、4 项导航、问候、3 张数字卡、4 行任务） | 粒度越细越贵；元素越少每件越大越好读 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 悬空贴落=clickup 语言核心签名（已验证的口味信号），本卡
+  与 graze-face-tour 共用 FloatWrap 模式——影子不可感等于没做
+- 与 brand-frame-snap 分工：那张是品牌框咔哒定位的
+  节拍戏；本卡是框先行+内容贴落的登场仪式，框只是序幕
+- 衍生方向备忘：视角旋转变体（镜头左→右弧线旋转+同时贴落）
+  曾被裁"改改再看"（要求所有组件同时贴落），已收敛进 neon-frame-orbit-drop 卡
+
+## 参考实现
+demos/ui-entrance/neon-frame-forerun/
+（NeonFrameForerun.tsx）
+原片出处：clickup-30.mp4

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/neon-frame-orbit-drop.md

@@ -0,0 +1,51 @@
+---
+name: neon-frame-orbit-drop
+一句话: 霓虹框先行描框后，镜头绕页面左→右弧线旋转，页面全部组件/文字**同帧**从空中往下贴合（同形软影同步收敛）——整体登场式的框内安放
+适用: 单页 UI 的一次性隆重登场（与巡礼/逐区亮相相对）；暗场霓虹调性段落的主视觉揭幕；neon-frame-forerun 的姊妹镜
+时长: 描框 ~0.5s + 旋转&同时贴落 ~2.5s + 落定 ~1s；全段 ~4.7s（140f，旋转到 128f 收住后留落定）
+能量: 中高（一次性的大动作，落定即静）
+标签: effects、camera
+---
+
+## 意图
+neon-frame-forerun 的孪生变体：同样框先行、内容后落，但镜头
+不是固定的——从页面左侧视角连续弧线旋转到右侧视角，旋转进行
+的同时全部组件从空中贴落。命门是**同时贴合**：所有组件和文字
+同帧起落、同帧贴合、软影同步消失——这是"整体登场"的语法
+（判例：错峰版被裁"应该是所有组件和文字同时从空中往下贴合"）。
+错峰贴落属于巡礼镜（graze-face-tour），一页一次性亮相
+必须齐落，节奏语义不能混用。
+
+## 动效核心
+- 霓虹描框：渐变霓虹框 ~14f 奔画成型（同 neon-frame-forerun）
+- 视角弧线：rotateY +38° → -26° 连续弧线（透视原点 30%→64% 随动
+  近似相机环绕），贯穿全片
+- 同时贴落：全部元素统一 LAND 时刻（归一化 ~0.52）——同帧离地
+  悬空、同帧空中下降、同帧贴合；FloatWrap 同形软影（blur/offset/
+  opacity 随高度）全体同步收敛
+- 背景霓虹管框群衬场，主面板落定后让位
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 贴落同时性 | 全元素同帧起落（零错峰） | **命门**；任何错峰都会读成巡礼语法（判例裁决原话见上） |
+| 视角弧线 | rotateY +38°→-26°、透视原点随动 | 弧度小读作抖动；只转不落=空转 |
+| 旋转×贴落耦合 | 贴落窗口居中于旋转行程 | 旋转完才落=两段戏；落完还在转=收不了尾 |
+| 悬浮高度/软影 | 同 graze-face-tour（100–180px、影随高度） | 影不可感=没做（累计判例） |
+| 描框 | ~14f 奔画 | 同 neon-frame-forerun |
+
+## 已知坑
+- 参数经占位素材两轮调校通过，非实战定稿，首次实战须以真实素材回验
+- **贴落节奏语义判例**（本卡与 graze-face-tour 互为反例）：
+  巡礼镜=错开起点+重叠并行下落；整体登场镜=全体同帧。选错语法
+  两边都会被裁
+- 与 neon-frame-forerun 分工：那张镜头固定、错峰贴落+页面点亮
+  三层咬合；本卡镜头旋转+同帧齐落。同段落二选一，别连用（同框
+  语言重复）
+- 弧线旋转是透视原点近似而非真实 3D 相机环绕，极端角度下框辉光
+  形变略平——实战若需大角度环绕考虑真 3D 场景
+
+## 参考实现
+demos/ui-entrance/neon-frame-orbit-drop/
+（NeonFrameForerunOrbit.tsx）
+原片出处：无对应原段

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/page-waterfall-wall.md

@@ -0,0 +1,51 @@
+---
+name: page-waterfall-wall
+一句话: 页面瀑布墙——真实页面截图切成 3–4 列在 3D 后仰墙面上差速反向无限滚动，视差 + 镜头缓推做"内容多到流不完"的一览
+适用: "多页面/多功能/多模板"体量感段落；montage 中段铺陈或 intro 后的产品广度镜头
+时长: 4–6s（无限循环体，时长由段落需要裁）
+能量: 中（流动陈列型）
+---
+
+## 意图
+流动式一览：让观众在几秒内"看到很多页面流过"，读感是体量而非细节。
+与 outro-group-photo-launch 分工：那是**聚拢式**一览（元素飞来围住
+字标定格合影，语义"属于同一产品"），本卡是**流动式**一览（内容持续
+流过不定格，语义"还有很多没给你看完"）。
+与 wall-reveal-moves 分工：那是整墙**入场动作**，本卡是墙的**持续状态**，
+可用那卡入场后交棒本卡续流。
+
+## 动效核心
+- lib 组件 `assets/lib/VerticalTicker.tsx`：父层 perspective(1000px)
+  rotateX(20°) scale(1.2) 后仰成墙；每列 [...items,...items] 翻倍 +
+  progress 取模 translateY 0→-50% 无缝循环；上下渐变遮罩收边
+- 差速反向是视差命门：3 列 loop 时长错开（如 12/9/14s），中列反向——
+  等速同向读作一张大图在滚，差速反向才读出"独立的列"
+- 镜头缓推寄生在外层（scale 1→1.06 线性铺满全镜），墙自身循环、
+  镜头单向，两个运动源方向不同不打架
+- 素材：真实页面截图切片（Q1 脱敏后），卡片级切块比整页长图好——
+  整页切片滚动时观众来不及读，卡片块有完整轮廓可辨识
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 列数 | 3（1080p）/ 4（超宽） | 2 列读不出"墙"，5 列单列过窄纹理糊 |
+| loop 时长 | 相邻列差 ≥25%（12/9/14s） | 差速太小视差读不出；最快列 <7s 开始读作"刷屏" |
+| 方向 | 中列反向（-1,1,-1 或交替） | 全同向=一张大图；反向列是"独立列"的最强证据 |
+| 倾角/透视 | rotateX 20° / perspective 1000px | >25° 顶部行文字透视压糊（Q2）；<12° 读不出墙面后仰 |
+| scale | 1.2 基础 + 缓推至 ~1.26 | 1.2 是补透视收缩的底值，低于它四角露底；demo 把放大与缓推放到外层 CSS zoom（布局级缩放），切片文字不被放大发软（Q2） |
+| 遮罩高度 | 200px | 太矮行硬进硬出；太高可视区剩不下 2 行 |
+| 循环周期 | -50% 位移必须恰等于单副本周期（内容高+n·gap） | lib 已用 marginBottom 保证；自写实现用 flex gap 会差 gap/2 跳帧 |
+
+## 已知坑
+- **参数借鉴自外部实现（remotion-3d-ticker），非实战定稿；
+  首次实战须以真实素材回验**
+- 每列 items 总高必须 ≥ 视口有效高（否则同屏见同一切片两次，穿帮）；
+  列间切片不要复用同一张图，同图同时出现在两列读作素材穷
+- 本卡是氛围/铺陈镜头不是信息镜头：切片上文字只求"看得出是真页面"
+  不求读完；想让观众读某一块，交棒 spotlight-hero-card 单主角处理
+- P4 去重：与 outro 合影同片共存没问题（一流动一聚拢），但全片
+  瀑布墙只出现一次，二次出现读作凑时长
+
+## 参考实现
+assets/lib/VerticalTicker.tsx（核心组件）；
+demo 见 demos/ui-entrance/page-waterfall-wall/（PageWaterfallWall.tsx / VerticalTicker.tsx）。

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/product-card-progressive-assemble.md

@@ -0,0 +1,56 @@
+---
+name: product-card-progressive-assemble
+一句话: 详情卡像被逐字段抓取般自建——一枚"填充光标"领先跳格，图→标题→分类 pill 依次 pop→原价出现后被划线降级、强调色新价 spring 跳出→正文逐行揭示且高亮块由左向右刷过→色卡点亮→按钮填满，整卡全程极慢 scale 前推
+适用: 商品/条目详情页的能力展示；"结构化抽取""自动填充""数据自己长出来"类叙事的主镜头
+时长: 约 5.7s（172f@30fps）
+能量: 中（连续小事件密集排布，无单点爆发；靠前推保持推进感）
+---
+
+## 意图
+一张详情卡直接淡入，观众只看到"有一张卡"。逐字段落位则把卡变成一份**正在被填写的
+表单**：每个字段各自到位，观众的注意力被牵着走一遍卡的信息结构——图在哪、标题在哪、
+价格在哪、正文重点在哪。价格划线降级是全片唯一的语义事件（不是"出现"而是"改变"），
+所以它被安排在中段最显眼的位置。
+
+## 动效核心
+（demo：瓷白 look，原生 1920 坐标；1520×840 详情卡占画宽 79%，商品是 video-shotcraft 自己：棚拍图里放标志，标题 Shotcraft、卖点与色卡都是它的）
+- 字段时间表直接用 30fps 帧号：光标到达 图 8 / 标题 20 / pill 30 / 价格 42 / 正文 76 / 色卡 96 / 按钮 114，
+  字段在光标到达后 2f 开始落位；同组内部间隔 3f（pill、正文行、色卡），跨组间隔 10–20f——间隔的疏密就是信息分组
+- 填充光标：钴蓝 2.5px 描边框 + 外圈 6px 淡光 + AUTOFILL 小签，在相邻两个字段框之间用不对称 in-out
+  （`cubic-bezier(.4,0,.2,1)`，6f）同时插值位置与宽高；最后收进按钮（ease-in 8f 淡出）。这是全片唯一的光效
+- 骨架槽位：字段落位前槽位里是浅灰骨架条，落位时骨架随进度淡出——"表单正在被填"不是"元素在出现"
+- 两种落位：`rise`（上移 10–26px + 6px→0 失焦淡入，expo-out 14f）给图/标题/价格/正文；`pop`
+  （物理弹簧 damping 13，scale 0.4→1 一次可见过冲）给 pill 与色卡；小件 pop、大件 rise
+- 价格降级 f62（$449 完整落位后 hold 18f）：6f 内同窗"scale 1→0.46 + 变灰 + 9px 删除线从左划过"，
+  f63 起钴蓝新价 Free（Apache-2.0 开源）弹簧（damping 14）从 1.18 收到 1，OPEN SOURCE chip f69 滑入
+- 马克笔高亮：钴蓝 16% 底块 `scaleX 0→1`（origin 左），f86 / f90 起各 6f——比字段落位还快，读作"笔一划过去"
+- 按钮：墨黑底色 f116 起 12f 由左向右填满，文案 f122 淡入
+- 整卡呼吸：`scale 1→1.035`（不对称 in-out）摊在 0–132f；入场 0–14f scale .96→1 + 上移 30px；末段 40f 静止定格
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 字段时间表 | 光标 8/20/30/42/76/96/114，落位 +2f | 同类字段间隔 3 帧、跨类间隔 10–20 帧；全部改成等间隔会读作机械点名 |
+| 光标跳格 | 6f，swift in-out，框形同步变形 | <4f 读作闪现；>10f 光标拖在字段后面，"领先抓取"变成"事后框选" |
+| 单字段行程 | 14f expo-out | 行程远大于组内间隔 → 同组几个字段同时在动，画面是"涌"而非"点" |
+| rise 位移 | 10–26px（按字号） | 大标题位移大、小字位移小；>40px 会与整卡前推的方向感打架 |
+| pop | 弹簧 damping 13，0.4→1 | pill 与色卡尺寸小，过冲不会撞到邻居，大件用 pop 就会显得廉价 |
+| 价格降级点 | f62（价格落位后 hold 18f） | 必须留出"先看清原价"的时间，紧贴落位会读作从来就是打折价 |
+| 新价 spring | damping 14，1.18→1 | 全片唯一的放大回弹事件；阻尼调小会抖两下，与旁边的划线动作抢注意力 |
+| 高亮刷过 | 6f，`scaleX` 从左 | 5–6f 是马克笔速度；>12f 读作背景色渐变而不是划线 |
+| 整卡前推 | `scale 1→1.035`，0–132f | 摊在 4.4s 上是纯呼吸；>8% 卡会撞到画框 |
+
+## 已知坑
+- 字段框（光标落点）是写死的绝对坐标：改字号或文案后要同步改 `F` 表里的 box，否则光标框不住字段
+- 最后一个字段在 ~f128 落定，之后 ~1.3s 只有极缓前推——给观众通读整卡的时间，别当成 bug 砍掉
+- 三行正文 `white-space: nowrap` 写死不换行（34px，行宽 ≤ 700px）。换更长文案或中文时会溢出卡边，
+  落地必须重新配字号与行长
+- 新价与折扣 chip 是绝对定位（按 112px 粗体数字宽度估的 x），换价格位数要重排，否则 chip 压字
+- 内容是 video-shotcraft 的示例填法（$449 划掉→Free、卖点文案、品牌四色色卡；$449 只是示意原价），字段结构本身才是可复用的部分。
+  换成真实商品数据后字段数量往往变化，时间表要按新的字段分组重排间隔
+- 高亮的起点（f86/90）晚于所在行开始落位（f78/81）8–9f；改行落位时间必须同步改高亮，否则出现"高亮先到、文字后来"
+- `BLUE`（钴蓝）是全卡唯一色相来源（光标 + 新价 + chip + 高亮），换品牌色改 look 的 accent 即可；其余全是中性色
+
+## 参考实现
+demos/ui-entrance/product-card-progressive-assemble/
+（ProductCardProgressiveAssemble.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/radial-wave.md

@@ -0,0 +1,49 @@
+---
+name: radial-wave
+一句话: 17×9 圆点阵列按到波源的欧氏距离错峰点亮，每点 scale 过冲到 1.5 再落回常亮，第一道波扫完后第二道亮蓝脉冲从外圈反向收拢回中心
+适用: 产品/品牌开场的"系统上电"一拍；也用作数据网格、节点地图、覆盖范围类叙事的建立镜头
+时长: 约 3.8s（114f@30fps）
+能量: 中高（起手爆发一次，波前过后转为常亮低能量底子）
+---
+
+## 意图
+把"很多点同时存在"这件静态事实，改写成"能量从一个源头扩散到全体"的动态事实。观众
+看到的不是一张点阵图，而是一次通电：中心先亮，亮度像水波推过去，走完之后整张阵列
+留在常亮态——为下一拍要放的内容铺好底。第二道反向波是回执，告诉观众这个系统会回应。
+
+## 动效核心
+- 阵列 17×9 共 153 点，dot 用百分比定位（`left:(c+0.5)/COLS`），因此改变行列数不需要
+  重算坐标；每点预存归一化距离 `dist = hypot(c-cx, r-cy) / maxD`（maxD = hypot(8,4)）
+- 第一道波：`seg(t, dist*0.35, dist*0.35+0.18, E.outCubic)`——起点由距离线性推迟（最外
+  圈延后 0.35），单点自己的行程恒定 0.18；波前是"起点错峰"而不是变速
+- 每点的 scale 不是简单 0→1，而是 `w1*(1+0.5*sin(w1*π))`：中途鼓到约 1.5 再收回 1，
+  正弦包络让过冲发生在行程正中而非落位时
+- 第二道波：`seg(t, 0.62+(1-dist)*0.25, +0.15)` 把偏移量反号（外圈先动），取
+  `sin(w2*π)` 做纯脉冲，叠加 0.8 的 scale 增量与 0.25 的透明度增量，走完不留状态
+- 脉冲峰值处（`pulse2 > 0.3`）硬切成 `#b9f2ff` 并挂 `0 0 12px #7fd8ff` 光晕——只有第二
+  道波带发光，第一道波全程是 `#6c8cff` 常色，两道波在视觉上不会混成一件事
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 阵列规模 | COLS=17 / ROWS=9（153 点） | 点数决定波前的"分辨率"；<8 列时距离分档太粗，波读作三四圈同心环在跳 |
+| 波速系数 | `dist*0.35` | 这个 0.35 就是波速倒数：调大波走得慢、拖尾长；>0.5 时最外圈要等到全片过半才亮 |
+| 单点行程 | 0.18（≈21f） | 决定波前的厚度；<0.1 波前锐利像扫描线，>0.3 全场几乎同时亮，扩散感消失 |
+| 过冲幅度 | `1+0.5*sin(w1*π)` → 峰值 1.5 | 系数 0.5 是"弹一下"的量；去掉正弦项就是平淡的 0→1 淡入，>0.8 点会互相咬边 |
+| 第二道波 | 起点 `0.62+(1-dist)*0.25`，窗 0.15，幅度 0.8 | 0.62 是两波之间的呼吸；提前到 0.5 以下会和第一道波尾巴叠在一起读作一团乱闪 |
+| 常亮底 | `opacity = 0.25 + w1*0.5 + pulse2*0.25` | 0.25 是未点亮点的存在感；调到 0 则波前之外一片黑，阵列的"规模"交代不出来 |
+| 高亮阈值 | `pulse2 > 0.3` 切色 + 光晕 | 阈值越低发光段越长；这是硬切不是渐变，阈值贴近 0 时会看到明显的开关跳变 |
+
+## 已知坑
+- 波源写死在几何中心（`cx=(COLS-1)/2, cy=(ROWS-1)/2`）。要改成从角落或某个"节点"起波，
+  必须同时改 cx/cy 与 maxD，否则归一化距离 >1，最外圈的起点会被推到 t=1 之外永不点亮
+- 末帧不完全静止：中心点（dist=0）的第二道波窗是 0.87→1.02，t=1 时才走到 87%，
+  `pulse2≈0.41` 仍在高亮。要做循环或干净收尾，得把第二道波起点压到 0.85 以内
+- dot 的 `width:10px` 与 `margin:-5px` 是绑定的一对（靠负 margin 居中），改点径必须同步改
+  margin，否则整阵列会朝右下偏半个点径
+- 颜色只有两档（常色 `#6c8cff` / 峰值 `#b9f2ff`），换品牌色要改这两处加光晕色共三处；
+  背景 `#0a0b10` 是发光的前提，白底上这套亮度脉冲基本看不见
+
+## 参考实现
+demos/ui-entrance/radial-wave/
+（RadialWave.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/research-card-stack-scroll.md

@@ -0,0 +1,57 @@
+---
+name: research-card-stack-scroll
+一句话: 深色论文卡每 12 帧一张沿右下轴线飞入中心叠压，落位带 1 帧压缩，只有最上一张全清晰渲染标题+作者+摘要，下方卡按堆积深度递增模糊变暗只露标题条，背景横向 grid 同步下移做速度参照
+适用: "读了大量资料/处理了海量文档"的量级交代；研究类、检索类、批处理类产品的能力镜头
+时长: 约 4.8s（144f@30fps）
+能量: 中高（匀速高频，无爆发但持续压迫）
+---
+
+## 意图
+要说的是"数量"，但一次给 13 张卡会读成一堵墙。改成流水线：卡一张一张进，每张都被
+读过（最上一张永远是全文渲染的那张），读完就沉进堆里变模糊。观众感受到的是持续不断
+的吞吐量，而不是一个静态的堆。背景 grid 同速下移是速度参照——没有它，堆积会读作
+"卡在原地缩小"。
+
+## 动效核心
+- 时间轴用真实帧号而非归一化 t：内部 `F=144`，每张卡的本地时间 `e = t*144 - i*12`，
+  一切编排（入场、堆积、深度）都以 `PER=12` 帧为节拍单位写死
+- 入场是 6 帧短促动作：`seg(clamp((e+6)/6), 0, 1, E.outCubic)`——注意起点是 `e=-6`，
+  即卡在自己的节拍到达前 6 帧就开始飞，`translateY(-40→0)` + `scale(0.94→1)`
+- 落位 squash：`e ∈ [0, 1.6)` 时 y 轴 scale 额外乘 0.97，只压 1.6 帧——短到读不出是
+  变形，只读作"砸实了"
+- 堆积漂移：落位后 `drift = e/12*30`，每个节拍向下 30px、向右 `XOFF=9`px，形成微微
+  向右下的轴线；轴线的存在让 13 张卡不是同心叠放而是有厚度的一叠
+- 深度衰减：`depth = min(1, drift/(30*3))`——三个节拍内衰减到底，`blur(depth*4)` +
+  `brightness(1-depth*0.25)`；再往下 `(drift-30*3.2)/(30*1.6)` 把 opacity 拉到 0 回收
+- 焦点唯一：`focus = floor(f/12)`，只有 `i === focus` 的卡显示 body（作者行 + 4 条摘要
+  骨架），其余卡的 body 直接 `opacity:0` 只留标题——"正在读的那一张"永远只有一张
+- 背景 grid：`translateY((f/12*30*S) % 24)`，位移量与卡的 drift 用同一个 `GAP=30`
+  推导，所以 grid 与卡堆严格同速；对 24px 取模让它无缝循环
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 节拍 | PER=12 帧/张，13 张 | 12f 是"紧但看得清"的下限；<8f 标题来不及读，>20f 量级感垮掉变成逐张展示 |
+| 入场行程 | 6 帧（outCubic），提前量 -6 帧 | 行程只有节拍的一半 → 每张在下一张来之前已经落定；行程 ≥ PER 时会有两张同时在飞 |
+| 入场位移/缩放 | `translateY(-40→0)`、`scale 0.94→1` | 40px 相对 96px 卡高是小幅——卡是"落进去"不是"飞进来"；缩放差只有 0.06，再大就读作弹窗 |
+| 落位压缩 | 1.6 帧，y 轴 ×0.97 | 3% 是刚好能感知的量；>6% 或时长 >3f 会看出橡皮变形 |
+| 堆积轴线 | 每节拍 y+30px、x+9px | 9/30 的比值决定轴线斜度；x 归零会变成正下方同心叠压，厚度感消失 |
+| 深度衰减 | `depth = drift/90`，blur 0→4px、brightness 1→0.75 | 90px（3 个节拍）内衰减完 → 画面里始终只有约 3 张是"半清晰"的；衰减距离拉长会让下方糊卡堆太厚，画面变脏 |
+| 回收窗 | `drift > 96px` 起淡出，48px 内到 0 | 回收太早会看到卡在画面中央消失；太晚 13 张全在场，DOM 与 blur 开销都上去 |
+| 内容坐标系 | 逻辑 420×250，整体 `scale(min(W/420, H/250))` | 所有像素值写在逻辑坐标系里，改画布尺寸不用重排；卡 296×96、字号 9.5px 都是逻辑值 |
+
+## 已知坑
+- 卡数与节拍是绑定的：`13 张 × 12 帧 = 156 帧 > F=144`，末两张在 t=1 时仍在入场途中，
+  末帧不是干净的静态。要做定格结尾，把卡数压到 `F/PER - 1` 以内（12 帧节拍下 ≤11 张）
+- `focus = floor(f/12)` 会超出卡数上界（f=144 时 focus=12，正好是最后一张）——加卡数
+  或改节拍后要确认 focus 不会长期指向不存在的索引，否则出现"没有任何一张是清晰的"
+- 全部时间常量都写死在 144 帧的假设上（`F=144`, `fr=f/F`）。改时长必须同时改 F，
+  否则节拍会随时长伸缩，12 帧的紧凑感丢失
+- 标题是 13 条真实感的论文标题占位、`preprint:24xx` 编号由索引生成，落地要换成项目
+  真实文档标题；`rand(i*5+k)` 生成的摘要骨架条宽度是确定性伪随机，不要换成 Math.random
+- 深色卡（`INK` 底 + `#2A2A2A` 描边）压在 `#FAFAFA` 浅底上是这套对比度的前提；卡色
+  改浅后 `brightness(0.75)` 的深度衰减几乎看不出来，需要改用 opacity 或灰度衰减
+
+## 参考实现
+demos/ui-entrance/research-card-stack-scroll/
+（ResearchCardStackScroll.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/row-embed.md

@@ -0,0 +1,36 @@
+---
+name: row-embed
+一句话: 内容行像卡片一样从空中降下、rotateX 收平、嵌入瞬间底边亮一道强调色的缝
+适用: "结构化数据长进页面"的详情页/列表镜头；行级内容的批量入场
+时长: 约 2s（12–68f）
+能量: 中
+---
+
+## 意图
+详情页的行不是"显示出来"而是"长进去"——每一行从空中降下并严丝合缝嵌入页面布局，嵌入瞬间的强调色缝是"咔哒"扣上的视觉拟音。
+
+## 动效核心
+- 行按越落越快的节拍逐条从上空飞入（末段带速度砸进槽位 + 纵向运动模糊），rotateX 从仰角收平，scale 略过冲后 press 回弹
+- 行位先盖页面真实底色补丁 + 极淡虚线槽位框占位，落地后补丁消失让纹理透出；槽位接触影随行接近收紧变实
+- 嵌入瞬间行底边一道 2px 强调色缝从中心向两侧展开后淡出
+- 相机同时缓缓下摇并微推近，行雨与运镜并行；取景全程被页面铺满
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 节拍 | cue = 12/22/31/39/46（间隔 10→7 递减），飞行 12f，最后一行 58f 落地、强调色缝 66f 收尾 ≤ 镜头 68f 预算 | 先算"最后一行何时落地"再定 cue 间隔——节拍×行数要对预算（同 document-typewriter-reveal 卡的核心算术） |
+| 飞行姿态 | `perspective(900px) translateY(−120·air) rotateX(16°·air)`，进度缓动 bezier(.5,0,.8,.75)（末段仍有速度），scale 1.06→0.995 再 4f press-bounce 回 1 | rotateX 收平是"嵌入"的关键读感；纯垂直下落读作贴纸 |
+| 飞行体 | backgroundImage 取整页截图、backgroundPosition 负偏移裁出该行 | 纹理裁片不重绘内容（Q1）——重绘的行和页面字体渲染有肉眼可见差异 |
+| 空槽补丁 | 行位先盖页面真实底色 #f9f6f1 patch（逐像素采样，偏白会读成一整块白板）+ 20% 虚线槽位框，落地后 2f 消失 | 无补丁时纹理里烤入的行会先透出来，飞入变成"重影" |
+| 嵌入闪光 | 底边 2px 强调色缝（两端羽化）从中心向两侧 5f 展开（Easing.out cubic）、8f 淡出，带 7px 辉光 | 缝只在底边、只闪一次；四边都闪读作选中框 |
+| 相机 | cy 500→740、zoom 1.12→1.25，68f 缓动下摇 + 微推 | 运镜与行雨并行制造"边看边长"的感觉；相机若等行落完再动，镜头会拖；起止两端都要让页面铺满画框，露出页顶/页底外就是空白死区 |
+
+## 声音
+段落切入钉 transition-soft（模板片钉在 f475）；行落地不逐条配音——行数多、间隔匀时逐条 pop 会机枪化，靠画面的强调色缝做"视觉拟音"即可（S2 反面自检）。
+
+## 已知坑
+- 飞入终点必须是页面布局真实槽位、落地即嵌入（Q9）——要"从空中飞入，嵌入 dashboard"；悬浮其上不落地会显得假
+- 强调色缝等光效必须裁进承载元素圆角边界内（Q4 判例），光溢出圆角是廉价感典型来源
+
+## 参考实现
+demos/ui-entrance/row-embed/RowEmbed.tsx（原 template/src/aifl/live/SceneDetail.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/value-stagger-gradient.md

@@ -0,0 +1,64 @@
+---
+name: value-stagger-gradient
+一句话: 16 根柱入场时 delay 是时间错峰，同时高度/色相/位移/模糊四个属性各自铺成从首到末的数值梯度；第二拍把错峰原点换成中心，脉冲幅度以中心为最大重新铺开
+适用: 技法演示与参数化能力的展示镜头；也可直接当数据/频谱/均衡器类界面的入场
+时长: 约 5.0s（150f@30fps）
+能量: 中高（第一拍是连续铺开，第二拍中心脉冲是明确的一次峰值）
+---
+
+## 意图
+stagger 通常只被用来错开时间。这张卡要说的是它还能错开**值**——同一个索引既决定
+"什么时候动"，也决定"动到多少"。两拍是一组对照实验：第一拍原点在首位（梯度从左到
+右单调铺开），第二拍原点换到中心（梯度以中轴对称铺开）。观众看到的不是两个动画，
+而是同一个配方换了一个参数。屏幕上的代码字幕同步换成对应的 stagger 调用，明说这件事。
+
+## 动效核心
+- 核心工具是一个 8 行的 `staggerVal(i, n, a, b, ease)`：把索引归一化成 `k = i/(n-1)`
+  再 `lerp(k, a, b)`——等价 anime.js 的 `stagger([a, b])` 值模式，可选 ease 让梯度非线性
+- 静态梯度（写在 setup 里，一次算完）：色相 `staggerVal(i,N,200,320)`、
+  最大高度 `staggerVal(i,N,92,32)`——16 根柱天生是一道从蓝到紫、从高到矮的斜坡
+- 动态梯度（每帧用）：位移量 `staggerVal(i,N,46,14)`、模糊量 `staggerVal(i,N,8,2)`
+  ——首位柱要走 46px、糊 8px，末位只走 14px、糊 2px。**同一次入场里每根柱的行程都不同**
+- 第一拍时间错峰：`d = i*0.02`，`e = seg(t, 0.06+d, 0.28+d, E.outCubic)`——从首位起，
+  16 根摊在 0.3 的窗上；`opacity = e`、`filter = blur((1-e)*b0)`、
+  `translateY((1-e)*y0)` + 高度 `hMax*e`（底部锚定按 height 生长，圆角不被 scaleY 压扁），三者都被同一个 e 驱动
+- 第二拍换原点：`distC = |i - 7.5| / 7.5` 是到中心的归一化距离，
+  `w = seg(t, 0.56 + distC*0.13, +0.18)`——中心柱先动，波向两端扩，这就是 `from:'center'`
+- 第二拍的幅度也是梯度：`amp = lerp(1-distC, 0.06, 0.42)`，中心柱脉冲 42%、末端只有 6%；
+  `pulse = sin(w*π)` 是纯脉冲，同时叠进高度 `hMax*e*(1+pulse*amp)` 与
+  `brightness(1+pulse*0.55)`
+- 代码字幕是一条语法着色的代码条，在 t≈0.52 用约 5f 上下交叉换句（旧句上移淡出、新句自下替入），从 `scale: stagger([1, 0.35])  hue: stagger([200, 320])`
+  换成 `pulse: stagger([.06, .42], { from: 'center' })`——正好卡在两拍之间
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 柱数 | N=16（`left: 8+i*5.4%`，宽 3.4%） | 16 根让梯度有足够分档；<8 根梯度读作"每根都不一样"而非一道斜坡，>24 根柱间距要重算 |
+| 时间错峰 | `d = i*0.02`（≈3f/根，总 0.3） | 3f 是连绵的铺开；>0.05 会变成逐根点名，梯度的"整体感"丢失 |
+| 单柱行程 | 窗 0.22（≈33f，outCubic） | 行程是总错峰的 0.73 倍 → 大部分时间十来根同时在动；行程 < 错峰总量时变成一根接一根 |
+| 高度梯度 | `stagger([92, 32])`px | 首末 2.9 倍差是明确斜坡；比值 <1.5 读不出梯度，>4 末端柱矮到看不见 |
+| 色相梯度 | `stagger([200, 320])` | 120° 跨度（蓝→紫）；跨度 <40° 时色相白给，>200° 会绕回红色让斜坡读作环形 |
+| 位移/模糊梯度 | `stagger([46,14])`px / `stagger([8,2])`px | 这两条是本卡的"值 stagger"主证据——把它们改成常量，动效立刻退化成普通的 stagger 入场 |
+| 第二拍原点 | `from:'center'`，`distC*0.13` | 0.13 是从中心到端点的传播延迟（≈4f）；归零则整排同时脉冲，`from` 参数就没有意义了 |
+| 脉冲幅度梯度 | `lerp(1-distC, 0.06, 0.42)` | 中心 42% / 端点 6% 是 7 倍差，波形明显；两端也给大幅度会读作整排一起鼓，中心原点看不出 |
+| 亮度脉冲 | `brightness(1 + pulse*0.55)` | 55% 提亮让脉冲在暗底上可读；这一项没做梯度（全柱同幅），是有意的——太多梯度叠一起观众读不清哪个是主角 |
+
+## 已知坑
+- 第一拍与第二拍首尾相接：末柱入场结束于 `0.28+15*0.02 = 0.58`，而中心柱的脉冲在 0.56
+  就起。加柱数或加大时间错峰会让入场吃进脉冲段，两拍糊成一件事——加柱必须把 0.56 后推
+- 端点柱的第二拍窗口是 `0.69→0.87`，之后到 t=1 有约 0.13（20f）的完全静止。这是给
+  观众看清"终态梯度"的时间，不是空白
+- `distC` 的分母 `C=(N-1)/2` 在 N=1 时会除零；`staggerVal` 里已用 `n<=1 ? 0` 兜住，
+  但 `distC` 没有——柱数改成 1 会 NaN
+- 柱位 `left: 8+i*5.4%` 与宽 `3.4%` 是为 N=16 手配的（末柱右缘 8+15*5.4+3.4 = 92.4%）。
+  改柱数必须重算这两个百分比，否则柱会溢出或挤在左半边
+- 字幕是 anime.js 的 API 调用字符串，本质是**技法说明**而不是内容。用在真实成片里
+  要么换成有语义的标题，要么去掉——否则观众读到的是代码
+- 底部的 16 个小圆点（`bottom:17%`，opacity .35）是静态装饰，不参与任何动画；它们的
+  `left` 偏移 `+1.2%` 是与柱宽 3.4% 手对的居中量，改柱宽要一起改
+- 深底（`#0a0b10`）+ 高饱和柱（85%/66%）+ 12px 光晕是一套；浅色主题下光晕与
+  brightness 脉冲都失效，需要改用 saturate 或阴影表达脉冲
+
+## 参考实现
+demos/ui-entrance/value-stagger-gradient/
+（ValueStaggerGradient.tsx）