dsh-drawai 0.3.4 → 0.4.1

package/lib/motion/shotcraft/upstream/references/shots/typography/word-relay-filmstrip.md

@@ -0,0 +1,57 @@
+---
+name: word-relay-filmstrip
+一句话: 左列黑白相间等高页面卡步进滚动（焦点卡全亮、邻卡离焦压暗）、右侧衬线大词原位接力（名词恒定+动词轮换）——切词瞬间才滚动一格，词块垂直中心与当前页面卡中点精确对齐
+适用: "一个主体 × 多种能力"的枚举段（Shotcraft frames/builds/ships…）；作品集/案例流展示；产品多场景巡礼
+时长: 每词期 ~1.5–2s × 3–4 词；demo 180f（6s）
+能量: 中低（编辑部气质，节奏靠切词的"咔哒"感）
+标签: ui-entrance
+---
+
+## 意图
+左边是证据（页面截图胶片），右边是论点（大词）：动词换一次，
+胶片就步进一格给出新证据——文字与画面互为注脚。命门是**步进制**：
+左列平时完全静止，只在切词瞬间滚动一格（滚动=换证据的机械动作），
+持续滚动会让左列沦为背景装饰、切词失去"咔哒"感。第二命门是
+**对齐**：大词块垂直中心必须与当前页面卡中点精确对齐（像素级），
+歪了整个版式的"编辑部严谨感"就塌了。
+
+## 动效核心
+- 舞台：graphite 近单色暗场 + 金色点缀；左列：等高页面卡（940×530，间距 105）纵向排列，
+  黑白（深浅）强制相间以显滚动步进；切词窗口内 18f 不对称 in-out（EASE.swift）滚动恰好一卡高，
+  其余时间零位移，快段叠纵向运动模糊
+- 景深：按离焦点距离 `dist = |卡顶 - 275| / 635`，邻卡压暗 `0.68·dist`、缩到 0.94、虚化 ≤3px——
+  步进时新证据"对焦"进来
+- 右侧：衬线体（Didot 类，140px）两行——主体名词「Shotcraft」正体次级墨恒定，动词斜体白字原位接力：
+  旧词 10f 灰化 → 切点起 8f ease-in 从遮罩上沿升出（先出），新词切点 +7f 起逐字母从遮罩下沿升起
+  （1.2f 错峰，金色句点最后到，后进），先出后进不许叠影（判例：v2 叠影"resebuilds"被抓）
+- 金色引线：从焦点卡右缘指向词块中线 y=540，切词起 6f 收回、切点 +10f 后 16f 重画；
+  词块上方 mono 序号 01/03、下方 32px 证据注脚随动词同步接力
+- 对齐：词块两行各一个 154px 行盒，`top = 540 - 154`，总高中心 = 当前卡顶 + 卡高/2 = y540@1080p
+  （精确到个位像素）
+- 滚动与切词同步：滚动起点=旧词开始灰化，滚动终点=新词落稳
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 页面卡 | 等高（530px@1080p）、黑白相间、约半屏宽 | 不等高/同色系读不出步进；卡太窄失去"证据"分量 |
+| 词期 | ~45–60f/词 | <40f 读不完词+胶片看不清；词期不必均匀 |
+| 滚动窗口 | ~16–18f 不对称 in-out，恰一卡高 | 持续滚动=命门违例；滚过头/不足读作机械故障 |
+| 词接力 | 旧词灰化后 8f 升出 → 切点 +7f 新词逐字母升起（16f/字母，1.2f 错峰） | 同帧交叉必叠影；间隙 >10f 读作断片 |
+| 垂直对齐 | 词块中心=当前卡中点（像素级） | 用户单点意见"文字高度和中间的页面中点要对齐"；差 >8px 可感 |
+| 字体 | 衬线 Didot 类、动词斜体白字 / 名词正体次级墨 | 无衬线会丢"编辑部"气质；动词要比名词亮，它才是换的那一个 |
+| 邻卡离焦 | 压暗 0.68·dist、缩 6%、虚化 ≤3px | 不压暗则邻卡和焦点卡抢戏；虚化 >5px 读不出是页面 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 text-column-converge 分工：那张是左右对峙合拢的揭晓戏；
+  本卡是纵向证据流+原位接力，无合拢无揭晓
+- 与 pill-slot-cycle 分工：那张是胶囊槽位轮换 UI 元素；
+  本卡是版式级的图文对位系统
+- 实战素材：页面卡应使用真实截图（demo 为手搓假页面——分镜脚本 / 渲染流水线 / 成片 PR 评审，每个动词停在
+  与之对应的证据卡上，残余差距已知）；截图亮度要人工分档保证相间可读
+
+## 参考实现
+demos/typography/word-relay-filmstrip/
+（WordRelayFilmstrip.tsx）
+原片出处：perplexity-promo.mp4 ≈76–90s

package/lib/motion/shotcraft/upstream/references/shots/typography/word-relay-geometry.md

@@ -0,0 +1,75 @@
+---
+name: word-relay-geometry
+一句话: 三个利益词各带一套专属几何接力——虚线大圆减速自转 + 彗星弧飞跑 → 三实线圆 trim 依次生长后收拢咬紧 → 镀铬金属 sheen 扫过后一拍收成纯白；旧词缩到 0.86 淡出，新词描边→填充揭示
+适用: 三点式利益陈述（更快/更好/更强）；品牌价值观段落；需要"一词一世界"的中段推进
+时长: 约 6.0s（180f@30fps：三段各 ≈60f，段间重叠 6f）
+能量: 中高（三拍推进 + 全程几何运动 + 背景粒子，无静止帧）
+---
+
+## 意图
+三点式利益陈述最容易做成三张字卡硬切。接力的做法是给每个词配一套
+**只属于它的几何**：虚线圆是"在转"（快）、三圆相扣并收拢是"互相咬合"（紧 / 好）、
+金属扫光是"材质硬"（强）——几何本身就在替形容词做论证。第三个词
+留了升格待遇（sheen 扫光 + 收白），因为它是结论。背景微尘、共用舞台光与底部
+三段进度条把三拍缝成一个连续空间，不然还是三张卡。
+
+## 动效核心
+（demo 版本：石墨暗场电影字卡，词表 Faster / Tighter / Stronger，1920×1080 原生坐标）
+- 三段按帧排：Faster 2→62、Tighter 56→122、Stronger 116→180；每段入场 14f（snappy，
+  `scale 1.06→1` + 10px 去虚）、出场 10f（exit 强 ease-in，`scale 1→0.86` + 12px 退焦），
+  交接重叠 6f 是交棒而非硬切；末段无出场，收白后 hold 22f
+- 每词三层文字（230px/800，静态字库 Helvetica Neue）：`outline` 层 `-webkit-text-stroke:2px`
+  + 透明填充，`fill` 层纯白——**描边先到位，填充后揭示**；三层共用 `padding: 0.08em 0.1em 0.28em`，
+  否则 mask / background-clip 只画在盒内，会裁掉 g 的下伸部与末字右沿、露出底下的描边层
+- 前两词的填充是 ±7% 柔边 `mask-image` 横向擦入（入场后 10f 起、18f，swift），描边层透明度
+  同步降到 0.2 留一点重影
+- Faster 的几何：虚线大圆（r=400、`dash 10 16`）+ 外圈 120 格刻度环（r=452，反向慢转），
+  入场 22f 从 0.4 snappy 长到 1，同时多转 160° 减速刹住（飞轮感），之后匀速慢转永不停；一道 16 段
+  渐隐的白色彗星弧沿 r=400 以 7.5°/帧飞跑——"快"由两层相对转速 + 彗星的速度差读出
+- Tighter 的几何：三实线圆（r=218）`pathLength=1` + dashoffset trim 生长，起笔绕各自圆心
+  `rotate(-90 cx 0)`，延迟 0/6/12f、各 22f（out），笔头一粒发光点长满即熄；92f 起三圆间距
+  340→300 收拢 14f（swift），落定时圆线提亮一次、四个相交点亮起菱形铆钉光点（overshoot 弹出）
+  ——"紧"是看得见的收拢动作
+- Stronger 无几何：120f 起描边 → 竖向镀铬渐变（亮顶—暗腰—亮底）；124→148f 一道带香槟暖色的
+  窄白带（`100deg`、`background-size:300%`）从左扫到右；146→158f 收成纯白 + 一次泛光脉冲，
+  脚下横向光带从 0.2 宽 snappy 展开，舞台主光同拍提亮——结论词独享的升格待遇
+- 词下 40px 副句给产品证据（rise 逐词升起，demo 是 video-shotcraft 的三句宣传），左上 mono 计数「01 / 03」、
+  右上镜刻标志 + video-shotcraft 小写字标、底部三段进度条（label 级纹理）；
+  相机全程 1→1.025 smooth 极缓推进（不抖）
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 三段时段 | 各 ≈60f，重叠 6f | 每词约 2s 是"读词 + 看几何"的下限；重叠 <3f 读作硬切，>12f 两词同屏打架 |
+| 入/出场窗 | 入 14f snappy / 出 10f exit | 出场比入场短是对的（退场要决绝）；出场用 out 曲线会读作"舍不得走" |
+| outline→fill | 18f swift，±7% 柔边，outline 留 0.2 | 留一点描边做重影是质感来源，降到 0 字变扁；窗 >30f 擦入慢得像加载条 |
+| 虚线圆 | r=400、`dash 10 16`、scale 0.4→1、入场多转 160° 刹住 | 刹车是"快"的第一证据；scale 起点 >0.7 就没有"长出来" |
+| 彗星弧 | 7.5°/帧、16 段渐隐 | 比环快 8 倍以上才读得出"速度差"；段数 <8 尾巴断成虚线 |
+| trim 生长 | 延迟 6f/圆、各 22f | 相位差是"依次相扣"的关键，同时生长读作三个独立圆 |
+| 收拢 | 间距 340→300（14f swift）+ 交点铆钉 | 收拢量 <20px 看不出动作；>60px 三圆挤成一坨 |
+| sheen 扫光 | `100deg`、`background-size:300%`、24f smooth | 300% 保证白带只占字宽一小段（=金属高光）；镀铬底层不能省，否则扫光前是一块灰字 |
+| 收白 | 12f + 泛光脉冲 + 脚下光带 | 这一下是全片唯一的"结论"待遇；删了三个词就是平级，第三点没有落点 |
+| 字号配色 | 词 230px/800、副句 40px、几何 `rgba(236,238,244,.42)`、graphite 暗场 | 几何比字暗一档是层级，几何比字亮就抢主角 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- **三个词必须是同一句法的三点（demo 都是比较级单词，6–8 字母）**：
+  时段是等长的，词长差大时几何（圆半径、间距）都是写死的坐标，
+  长词会顶出虚线圆或压到相扣圆上——换词表要同步调 r 与收拢间距
+- `-webkit-text-stroke` 是前缀属性：Chromium/WebKit 才有，Firefox 下描边层
+  直接是透明（词消失）。Remotion 渲染走 Chromium 无碍，但预览环境要注意
+- SVG trim 用的 `pathLength=1` 归一化在部分老版本浏览器上对 `<circle>`
+  支持不全，退化表现是圆一次性全画出（丢生长感）——移植时先在目标
+  渲染器上验一帧
+- 出场 trim 是"入场 trim 减出场 seg"直接相减：两段窗若靠得太近
+  （段长 <40f）会出现还没长完就开始收，圆只画出一小段
+- sheen 层与 fill 层是叠着的两个 DOM：切换靠透明度交叉，若把 `white` 窗
+  与 `sh` 窗调成重叠不足，会有 1–2 帧两层都半透（字发灰）
+- 第三个词的升格待遇只能给一次：全片三个词都上 sheen 就没有结论感
+  （P4 手法去重精神）；声音上三次入场是三个节奏点，第三个词的收白值得
+  单独一记重音，配法纪律见 sound-design.md
+
+## 参考实现
+demos/typography/word-relay-geometry/
+（WordRelayGeometry.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/avatar-bracket-carousel.md

@@ -0,0 +1,59 @@
+---
+name: avatar-bracket-carousel
+一句话: "Your ___ agent" 填空排版，四角对焦框钉在句中不动，头像队列在框内垂直 spring 轮换三次，入框放大清晰、出框按距离缩小淡化模糊，角色标签同步更换，切换瞬间对焦框呼吸 7%
+适用: "一个位置，多种角色"的能力枚举；团队/身份/预设/人格类产品的核心一句话镜头
+时长: 约 5.2s（156f@30fps）
+能量: 中（三次等距切换构成稳定节拍器，对焦框脉冲是唯一装饰性动作）
+---
+
+## 意图
+"我们的 agent 能当导演、剪辑、动画师、音效师"列成四行就是一张清单。塞进一句话的一个槽位里，
+它变成一个承诺加四次证明：句子不动，只有槽里的人在换。四角对焦框是这个手法的关键
+——它不参与轮换，但它把观众的眼睛钉死在那 92×92 的方框里，所以四次更换才读作
+"同一个位置"而不是"四张头像飘过"。
+
+## 动效核心
+- 位置量 `pos` 是三段 spring 的累加：`[0.24, 0.46, 0.68].forEach(s0 => pos +=
+  seg(t, s0, s0+0.14, k => E.spring(k, 0.25)))`——不是索引跳变，而是连续量，所以任意
+  时刻都能算出每个头像离槽位有多远
+- 距离驱动一切：`d = |k - pos|`，然后 `scale = max(0.5, 1-d*0.38)`、
+  `opacity = max(0, 1-d*0.62)`、`blur = min(3, d*2.4)`、`translateY = (k-pos)*76`——
+  四个属性同源于一个距离量，所以入框/出框的变化天然同步，不需要单独排时间
+- 队列是绝对定位在 `slot` 的 0×0 锚点上叠放的（`left:-29px, top:-29px` 自居中），
+  垂直位移全靠 `(k-pos)*STEP`；框外的头像照样在渲染，只是被 opacity 和 blur 藏掉
+- 入场是叠在轮换之上的另一层：`el.style.opacity = op * seg(t, 0.02+k*0.03, 0.12+k*0.03)`
+  ——四张按 0.03 错峰在开场 0.15 内建立队列，之后这一项恒为 1，轮换全权接管
+- 角色标签独立一套但共享 `pos`：`opacity = max(0, 1-|k-pos|*2.2)`，衰减斜率 2.2 比
+  头像的 0.62 陡得多——标签在 0.45 格距离外就完全消失，永远不会出现两个标签同屏
+- 对焦框呼吸：`breath = Σ sin(seg(t, s0, s0+0.1) * π)`，取 `min(1, breath)` 后乘 0.07
+  加到 scale 上；正弦包络让脉冲在切换动作的正中达峰，走完归零
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 切换点 | 0.24 / 0.46 / 0.68，间隔 0.22（≈34f / 1.14s） | 间隔就是"读得完一个角色"的时长；<0.12 观众来不及看标签，>0.3 节拍器感散掉 |
+| 切换行程 | 窗 0.14（≈22f），`E.spring(k, 0.25)` | 行程占间隔的 64% → 静置时间约 12f；阻尼 0.25 是明确一次回弹，调小会抖两下与相邻切换互相干扰 |
+| 步距 | STEP=76px（框 92px、头像 58px） | 步距必须大于头像直径否则相邻两张会咬边；76/92 意味着出框的头像仍露出一角，队列的存在被暗示 |
+| 缩放衰减 | `1 - d*0.38`，下限 0.5 | 一格距离缩到 0.62；斜率调大出框更决绝，但下限 0.5 会更早触顶，队列变成"两档尺寸" |
+| 透明度衰减 | `1 - d*0.62` | 1.6 格距离外完全消失 → 画面里始终有约 3 张可见；斜率降到 0.3 会看到整列四张都在，取景框的"锁定"语义被削弱 |
+| 模糊衰减 | `d*2.4`，上限 3px | 模糊是景深暗示，2.4 的斜率让邻位约 2.4px；>4px 邻位糊成色块，队列读不出是头像 |
+| 标签衰减 | `1 - d*2.2` | 斜率必须显著大于头像的 0.62——标签是文字，两句同时半透明叠着最难读 |
+| 框脉冲 | 窗 0.1，`sin(·π)` × 0.07 | 7% 是"咬合了一下"的量；>15% 框自己变成主角，抢过头像更换 |
+
+## 已知坑
+- 四张头像对三次切换：`pos` 最终停在 3，正好是末位。加第五张必须加第四次切换（且
+  末次切换要在 0.86 之前结束才有静置时间），否则队列末尾永远进不了框
+- 切换点是硬编码数组，出现两处（`pos` 累加与 `breath` 累加）。改节拍必须同时改两处，
+  漏改一处会出现"框脉冲和头像换位错开"
+- 入场 stagger 与首次切换的间隔只有 0.09（入场末 0.15 → 切换 0.24）。加头像数会推后
+  入场结束点（`0.12+k*0.03`），5 张以上就要把首次切换往后挪
+- 头像是白色线性图标 + 中性灰阶受光渐变圆（灰度分层仅用于区分队列项），强调色只用在对焦框的
+  四个 SVG 角标上（及标签 chip 的一粒圆点）——落地换成真实头像后仍应保持这个分工，头像本身别抢色
+- 对焦框 SVG 的四条 path 与 92×92 viewBox 是写死的坐标（`M4,26 L4,4 L26,4` 等）。改
+  框尺寸要整套重标，只改容器宽高会让角标缩放失真
+- 句子 "Your ___ agent"（demo：video-shotcraft 的 agent 摄制组 Director / Editor / Animator / Sound）用 flex + gap:22px 居中，槽宽固定 92px 所以句干不会因
+  头像更换而重排——但换成中文句子时要确认槽两侧的字宽变化不会让槽偏离画面中心
+
+## 参考实现
+demos/ui-entrance/avatar-bracket-carousel/
+（AvatarBracketCarousel.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/bezier-source-converge-merge.md

@@ -0,0 +1,67 @@
+---
+name: bezier-source-converge-merge
+一句话: 左侧四个来源节点各有一条细贝塞尔曲线连向右侧同一汇聚点，曲线先错峰由左向右 draw-on，节点沿自己的曲线滑向汇聚点并三段式加速缩小到消失，强调色数据包全程沿路径滑行，吞并完成后曲线从左端反向擦除只留品牌标志（demo：白瓷圆片托 video-shotcraft 镜刻标志）
+适用: "多源整合/统一接入/数据汇聚"的核心机制镜头；集成、聚合、单一入口类产品的说明段落
+时长: 约 5.6s（168f@30fps）
+能量: 中（长镜慢速推进，靠数据包滑行维持活性；吞并瞬间是唯一小高点）
+---
+
+## 意图
+"我们把四个来源统一了"是一句抽象话。这个动效把它变成可看的物理过程：先建立四条独立
+的通路（draw-on 是"连上了"），再让四个来源真的顺着通路走进同一个点并被吸进去（缩小
+到 0 是"被吞并"），最后擦掉通路只留品牌标志（"现在只有一个"）。三段叙事各自有明确的
+起止，观众不需要旁白就能读出因果。
+
+## 动效核心
+- 路径几何：每条 `d = "M -22,y L 74,y C 186,y 214,120 332,120"`——起点在画框外 -22，
+  74 处是来源节点的驻留位，之后一段三次贝塞尔弯向汇聚点 (332,120)。四条只差起始 y
+  （36/92/148/204），所以它们的曲率天然不同，汇入角度也不同
+- draw-on 用 `stroke-dasharray = len` + `dashoffset = len*(1-draw)`，`seg(t, 0.04+i*0.045,
+  +0.17, E.outQuad)`——0.045 的错峰让四条线像被依次接通而不是一起亮
+- 节点定位用 `getPointAtLength`：x=74 恰是直线段终点，直接标定路径比例
+  `f0 = 96/len`（原 40 步扫描精度不足，四节点会排不成一列），运行时 `frac = f0 + (1-f0)*conv`，`conv = seg(t, 0.34, 0.74, E.inOutCubic)`——
+  节点是**沿真实曲线**走的，不是两点间插值
+- 三段式缩小：`conv < 0.75` 时 44→15px（缓慢瘦身），`conv ≥ 0.75` 时 15→0px（最后
+  1/4 行程掉光）——后段的尺寸变化率是前段的 4 倍多，这就是"被吸进去"的加速感；
+  字号跟着 `size*0.26` 同步缩，标签不会脱离节点
+- 数据包：`pkCycle = (seg(t, 0.1, 0.74, E.linear)*2) % 1` 走两个整数周期，各路加
+  `i*0.13` 相位偏移；透明度用 `1 - |cycle-0.5|*0.6` 让包在路径中段最亮、两端淡——
+  避免看到包在起点凭空出现
+- 擦除：`erase = seg(t, 0.78, 0.9, E.outQuad)` 把 dashoffset 推成负值（`-erase*len`），
+  于是虚线从**起点**方向退走，方向与 draw-on 相反，读作"通路收回"
+- 徽标：`seg(t, 0.16, 0.26)` 淡入并从 0.7 放到 1，吞并时刻（0.7→0.78 outBack 加 12%，
+  0.78→0.86 outQuad 减回）做一次接收脉冲；末尾 `endCap` 字幕在 0.84 后淡入
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 来源数 | 4 条（y=36/92/148/204，间距 56） | 4 条是曲率差异明显又不打结的甜点；>6 条中间几条的贝塞尔几乎重合，汇入角读不出区别 |
+| draw-on | 起点 `0.04+i*0.045`，窗 0.17，outQuad | 0.045 的错峰约 7f；归零会读作四条线一起刷出，失去"逐路接通"的语义 |
+| 汇聚窗 | 0.34→0.74（inOutCubic） | 占全片 40%，是主段落；inOut 的缓起是"启动"、缓收是"到位"，换 linear 立刻变成匀速传送带 |
+| 三段缩小 | 44→15px（前 75%）→ 0（后 25%） | 拐点 0.75 越靠后吸入越突然；把它挪到 0.5 会变成"一路缩小"，吞并的那一下就没了 |
+| 数据包周期 | 2 个整数周期（0.1→0.74 线性） | 必须是整数周期，否则末帧包停在半路；周期加密到 4 会读作数据流很急，也更容易和节点重叠 |
+| 包相位偏移 | `i*0.13` | 错开四路的包，避免它们排成一行同时汇入；0 会看到四个包整齐并进，像一次发车 |
+| 擦除 | 0.78→0.9，dashoffset 取负 | 12f 完成；擦除必须在节点全部消失（conv=0.74 结束、节点 0.92 前淡完）之后，否则线先没了节点悬在空中 |
+| 徽标脉冲 | outBack +12%（0.7→0.78）→ 回落（0.78→0.86） | 12% 是"接收到了"的量级；>25% 会抢过汇聚本身的注意力 |
+
+## 已知坑
+- `getTotalLength` / `getPointAtLength` 必须在 SVG 已挂到文档且完成布局之后才有效，
+  代码用 `ready` 标志在首帧 `prime()` 里做——移植到 Remotion 时首帧渲染可能拿不到
+  长度（fallback 写了 `|| 380`）。稳妥做法是在 `useEffect`/layout 后再算，或预先算好
+  常量表，否则首帧会出现一次错位跳变
+- `f0` 直接按直线段长 96 标定（`96/len`）。旧版用 40 步线性扫描，精度只有 1/40，节点驻留位
+  会偏离 74、四个节点排不成一列——改路径（尤其直线段长度）后要同步改这个标定
+- 节点 opacity 在 `conv > 0.92` 后才开始淡出，而 conv 在 t=0.74 就到 1，所以节点是在
+  尺寸缩到 0 时消失而不是淡出消失。这是有意的（被吸进去不该淡出），但如果把三段式
+  拐点改晚，会看到节点在有尺寸时突然消失
+- 节点是灰阶线性图标（demo：页面截图/镜头卡/代码/声音四种素材）的白瓷占位圆（灰度分层仅用于区分四路），落地可换成真实来源
+  logo；强调色只留给数据包与涟漪，不要给节点上色，否则汇聚点的视觉主体被夺走。汇聚点的标志要托在一枚不透明的
+  圆片上——曲线终点与数据包都落在汇聚点中心，开口形标志（如镜刻取景框）直接放上去会从缺口里露出线头
+- 汇聚点 (332,120) 与 SVG 视口 440×240、`overflow:visible` 是绑定的一组坐标。改画布
+  比例要整套重标，路径起点 -22 依赖 `overflow:visible` 才能露出画框外的一截
+- 字幕 "From screenshot to showreel"（video-shotcraft 宣传语），出现在 0.84 之后——如果要配旁白，这句的
+  出现点应对齐旁白落词而非动画节点
+
+## 参考实现
+demos/ui-entrance/bezier-source-converge-merge/
+（BezierSourceConvergeMerge.tsx）

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

@@ -0,0 +1,60 @@
+---
+name: card-stack
+一句话: 一组模板卡（demo 9 张）从屏幕下方逐张 spring 弹入、越落越快叠成一摞，全员落位后整摞一次性展成扇面——每张按序号偏转 6.5°、横移 138px，最后中心卡被抽出
+适用: 需要交代"我们有一组东西"的产品段落；卡片墙/模板库/方案列表的建立镜头，也能当 logo 前的一拍蓄势
+时长: 约 5.0s（150f@30fps）
+能量: 中高（入场是连续小爆发，展开段收成一次平滑的整体动作）
+---
+
+## 意图
+一摞卡先聚成一个物体，再摊开成一组物体——顺序很关键：先给"整体"再给"个体"。
+观众第一眼记住的是有分量的一摞（数量感），第二眼才看清每张不一样（多样性）。
+展开动作留到最后一次性完成，是为了不和入场的节拍打架。
+
+## 动效核心
+（demo 版本：瓷白模板库发布——video-shotcraft 镜头配方库，9 张 320×440 镜头 / 模板卡，1920×1080 原生坐标）
+- 两层运动分离叠加：入场（每张自己的弹簧）与扇形（全员共享的一条展开进度），
+  最终 transform 是 `translate3d(tx, y, tz) rotate(rot)` 里两层各自算出的分量合成
+- 入场：起跳帧 `2 + stagger(i, 9, 40, EASE.out)`——EASE.out 映射让间隔先大后小（砰——砰—砰-砰砰，越来越快）；
+  每张 `springAt(f, start, {damping:13, stiffness:150})`，`y` 从 820px 抬到 0（起点在画框外），≈20f 落座；
+  飞行中带 ±9° 交替倾角并随落座收敛，按竖向速度加运动模糊（≤10px）
+- 重量：每张落座（起跳后约 6f 越过终点）时整摞被压低 5px（sin 包络 9f）；成摞时确定性 ±3.2° / ±11px 错位，
+  像随手码齐的一摞；展开前 62–72f 整摞收紧 2%（预备）
+- 扇形：`springAt(f, 68, {damping:20, stiffness:95})` 是唯一的展开时钟（带一次轻微过冲 = 手腕甩开的惯性），
+  终态 `k = i-4`，`rot = k*6.5°`、`tx = k*138px`；`transform-origin: 50% 130%` 把旋转轴放到卡片下缘之外——
+  扇柄在手里，卡片是绕手腕转开的
+- 叠压次序 = 序号（`zIndex = i`，左压右，像手里摊开的一手牌），全程不换——成摞时顶牌就是最后一张，
+  展开时不会出现顶牌跳变
+- 相机：成摞段 1→1.06 极缓推近给"一摞"分量，展开同段（64→106f）拉远到 0.88 让扇面完整入画；
+  地面接触影随扇面从 220 变宽到 760
+- 结尾：中心卡（钴蓝实色封面：镜刻标志反白版 +「Launch」，卡名 Launch film）沿自身轴抽出 72px（overshoot）+ 3px 钴蓝描边 + 一次扫光（Q4），
+  标题 "Start from a shot recipe."（88px）逐词升起、副句跟随，hold 28f
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 卡数 | N=9（奇数，中心卡独占中位） | 9 张 × 6.5° = 52° 总张角是舒适上限；>11 张要把每张角度降到 4–5°，否则两端卡飞出画框 |
+| 入场 stagger | 40f 跨度，EASE.out 分布 | 越来越快是"一串"的手感；等差分布读作逐张点名，<20f 读作一团一起冒 |
+| 入场行程 | y 820→0，spring damping 13 | 起点必须在画框外；damping <10 回弹两次以上，成组时抖动互相干扰 |
+| 落座下压 | 5px，sin 9f | 这是"有分量"的来源；>10px 整摞像弹簧床 |
+| 展开弹簧 | damping 20 / stiffness 95 | 一次轻微过冲像手腕甩开；damping >26 无过冲读作机械展开，<16 扇面来回晃 |
+| 扇形张角 | `k*6.5°`，横移 `k*138px` | 角度与横移要同比调：只加角度不加横移，卡会互相穿插 |
+| 深度 | `tz = i*2`，perspective 1800px | 只做叠压的暗示；深度主要靠叠压次序 + 两层软阴影 |
+| 旋转轴 | `transform-origin: 50% 130%` | 130% 决定"扇柄"离卡多远；改成 50% 50% 立刻退化成风车式散开 |
+| 抽卡 | 72px overshoot + 描边 + 扫光 | 只给中心卡一次；抽出量 <40px 看不出"被选中"，>120px 卡与标题打架 |
+
+## 已知坑
+- 两段时间窗刚好首尾相接：末张 42f 起跳、≈62f 落座，62f 预备、68f 展开。
+  加卡数或加大 stagger 会让入场吃进展开段，出现"还在飞就开始转"的浑浊——加卡必须
+  同步把预备与展开起点往后推
+- 卡数为偶数时 `k` 取半整数（±0.5, ±1.5…），没有中心卡，结尾"抽出主角"会偏在一侧；
+  demo 用 9 张。若改用"中间压两边"的 zIndex，要注意成摞→扇面时顶牌会跳变
+- 卡片 320×440 以 `left = CX-CW/2, top = CY-CH/2` 居中，扇柄位置随 CH 变；改尺寸要同步检查
+  两端卡是否出安全边距（相机 0.88 时最外卡角距画边约 100px）
+- 卡面是手搓的模板封面占位（生成式封面图 + 标题 + mono 元信息），落地应换成真实页面切片；
+  封面只用钴蓝 / 青绿 / 墨三色的浅色调，只有中心卡用钴蓝实色——真实素材里也要留一张「主角」
+- 展开同段（64→106f）相机拉远到 0.88，保证两端卡不出画；要接下一镜可在抽卡落定（≈120f）后切，别让扇面白停太久
+
+## 参考实现
+demos/ui-entrance/card-stack/
+（CardStack.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/carousel-3d.md

@@ -0,0 +1,66 @@
+---
+name: carousel-3d
+一句话: 8 张卡排成圆环整环自转一圈（匀速底 + 每 45° 一次停靠的分步），每卡只绕 Y 公转、自身 billboard 朝外，正反两层同向贴图配 backface-visibility:hidden 保证任何时刻都正立不倒置，正前方卡被点亮、环下字幕随之换字，相机全程钉在浅俯角
+适用: 作品集/模板库/集成清单的循环展示；需要无缝 loop 的背景拍或落地页 hero
+时长: 约 5.6s（168f@30fps）
+能量: 中（可无限循环的稳态运动，每 45° 一次停靠给出节拍）
+---
+
+## 意图
+展示"一组东西"最省事的办法是排成一排横滑，但横滑有起点和终点。环形没有——它天然
+循环，观众看多久都不会觉得"放完了"。这张卡真正要解决的是环形 carousel 最容易翻车
+的点：卡片背面。方案是双面同向贴图，所以从环内看和从环外看是同一张正立的卡，环转一圈
+不会有任何一帧出现镜像或倒置。
+
+## 动效核心
+（demo 版本：酸柠石墨暗场 video-shotcraft 镜头配方画廊，卡 340×460、半径 700px，1920×1080 原生坐标）
+- 环上定位公式只有一行：`transform: rotateY(i*360/N) translateZ(RADIUS)`——先转到自己
+  的方位角再沿新的 Z 轴推出半径。这一步同时完成了排布与 billboard：卡的法向天然朝外；
+  转到正前方的卡沿法向多推出 44px（只平移不旋转），停靠时读作"被选中"
+- 整环自转靠父层：`ring.transform = rotateY(-spin)`，卡自身的 transform 只有定位分量。
+  **卡永不绕 X 或 Z 转**，这是"永远正立"的根本保证
+- 转角不是死匀速：`turn = 0.5·f/168 + 0.5·stepPart(f)`，`stepPart` 每 21f 一步（8f 停靠 + 13f smooth 换位）。
+  匀速底让整环永远在走（loop 稳态），分步层每 45° 给一次"推一把—停靠"；8 步 × 21f = 168f 正好一圈，
+  f=168 时 turn=1，首尾帧逐像素可接
+- 双面同向贴图：front 与 back 用**同一份卡面**，back 额外加 `rotateY(180deg)`，
+  两层都设 `backface-visibility:hidden`。于是环外看到 front、环内看到 back，两者内容
+  朝向一致——如果只用一层，转到环背面时会看到镜像文字
+- 正前方点亮：`hl = smooth(1 - |方位角|/26°)`，驱动荧光描边、图形色（石墨灰 → 荧光黄绿插值）与外推量；
+  环下方字幕（mono 编号 + 72px 名称）在裁切窗里随分步层上滚换字，停靠时定格
+- 相机固定，一帧都不动：`perspective: 2200px`，环容器 `translateZ(-RADIUS) rotateX(-9deg)`——
+  正前方卡落在 z=0（按原生尺寸栅格化，文字不糊），所有运动都来自环的自转，这是"画廊"而不是"过山车"
+- 地面：2.7 倍半径的反光盘 + 96 格刻度环（随环同转）`rotateX(90deg)` 躺平在卡脚下；再叠一份以地面为镜面
+  `scaleY(-1)` 的倒影环（叶子层 8% 透明度 + 渐隐 mask，透明度不能挂在 preserve-3d 容器上，否则整环被拍平）
+- 空气透视：按卡的方位角 `(1-cos θ)/2` 给卡面叠一层底色（最后方 70%），环的前后关系一眼可读
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 卡数 | N=8（方位角间隔 45°） | 8 张在 700px 半径上前后互不遮挡；>12 张卡会互相压边，需要同步加大 RADIUS |
+| 半径 | RADIUS=700px（卡 340×460） | 半径/卡宽 ≈2 是疏密甜点；<1.5 倍时环背面的卡从正面卡的缝里挤出来，画面变乱 |
+| 转速构成 | 50% 匀速 + 50% 分步（21f/步，停靠 8f） | 分步比例 >70% 停靠时整环几乎停住，loop 读出"卡顿"；<30% 停靠感消失，又回到平的匀速 |
+| 圈数 | 全片 1 圈（8 步） | 圈数与步数都必须是整数才能 loop；非整数则末帧跳变 |
+| 透视 | `perspective: 2200px` | 相对 700 半径是较平的透视；调到 1200 以下近处卡会夸张放大，读作鱼眼 |
+| 相机俯角 | `rotateX(-9deg)` | 只是"略微俯视"，刚好露出地面盘与刻度环；>-20° 环会压扁成椭圆 |
+| 点亮窗 | 方位角 ±26° | 窗太宽相邻两张同时半亮，主角不明确；太窄换位途中整环全灰 |
+| 倒影 | 8% 透明度，62% 起渐隐 | >15% 倒影里的文字可读，会和下方字幕打架 |
+
+## 已知坑
+- 稳态循环是这张卡的特性也是限制：**它没有开头也没有结尾**。分步停靠给了节拍，但当主镜用
+  仍偏平，适合当背景层、loop 素材或与前景文字/相机运动叠加使用
+- 每帧都重设了 8 张卡的 transform（`rotateY(i*45) translateZ(RADIUS + 44·hl)`）——旋转分量恒定，
+  只有沿法向的外推随点亮变化。这让"卡自身不参与旋转"在代码里显式可见；不要把外推挂到旋转上
+- `backface-visibility:hidden` 在部分 WebKit 下需要 `-webkit-` 前缀（代码里已双写）。
+  漏掉前缀会看到两层 face 同时可见，卡片内容叠成一团
+- 卡面是手搓的镜头配方卡占位（mono 编号 + 生成式图形 + 大数字 + 名称），落地要换成真实截图，
+  **且 front/back 必须换成同一份内容**，否则双面同向的前提被破坏
+- 环转到背面时卡是"背对观众的正面"（看的是 back 层），所以内容始终可读——但也意味着
+  没有"翻面揭示"的余地。要做翻面必须放弃 backface-hidden 方案，另起一套
+- 深色柔光背景 + 石墨卡面 + 空气透视压暗是一套；换白底后压暗层与倒影都要重配
+  （压暗改成向背景色混合，倒影透明度降到 5% 左右）
+- 字幕的"当前卡"取自分步层的步号，不取自真实方位角：匀速底在停靠期间会让环多走约 8.6°，
+  正前方卡略偏左是正常的；若改分步比例，要确认停靠时点亮窗（±26°）仍罩得住这段漂移
+
+## 参考实现
+demos/ui-entrance/carousel-3d/
+（Carousel3D.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/cloner-depth-echo.md

@@ -0,0 +1,40 @@
+---
+name: cloner-depth-echo
+一句话: 克隆纵队——主卡瞬间"复印"出 7 个半透明分身沿斜向纵深排开成队，停一拍后全体加速吸回本体合一+弹跳
+适用: "多副本/多租户/规模感/批量处理"卖点；一镜讲完"一个=很多"
+时长: 138f（约 4.6s）
+能量: 中（陈列-收束型）
+---
+
+## 意图
+Spline/C4D Cloner 语汇的 UI 翻译：一张主卡"啪"地复印出 7 个克隆体
+沿 Z 轴向后等距排开（间隔 250px、透明度 100%→28% 递减、越远越只剩轮廓），
+错峰弹出成纵队；停 ~32f 让观众数得清"有很多个"；然后全体 ease-in 加速吸回
+本体合一，合体瞬间本体弹 1.06x 收束。demo 把"一个=很多"落到具体卖点：
+一张 video-shotcraft 渲染卡（launch-film）×8 个镜头，合体时卡底 8 个镜头位同时点亮，标题落「One prompt. / Eight shots.」。与 depth-layer-moves 视差
+（不同内容分层）分工：这是**同一内容**的等距重影阵列，语义是规模
+不是空间。
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 纵深排布 | 真 3D 透视 perspective 1500，消失点放在左上（360,120）；克隆体 translateZ = −250·idx，再叠 dx=−58·idx / dy=−6·idx | **命门**：纯 translateZ 且消失点在正中时克隆体全被本体挡住（不可感）；把消失点挪到画面一角，后退本身就把纵队排向那一角 |
+| 克隆数/间隔 | 7 个 / 250px | 少于 5 读不出"队"，多于 9 尾部糊成一团 |
+| 衰减 | 透明度 100%→28% 线性；填充褪掉只留强调色描边；越远附加 0→1.6px 景深虚化 | 越远越淡、越"只剩轮廓"=纵深证据；克隆体只留顶栏 + 折线 + 镜头号，别重复大读数（叠成一团乱码） |
+| 排开/吸回 | spring 错峰 2.2f/个（damping 15，一次轻过冲）；吸回强 ease-in 10f 全体同步，按纵深速度加拖影模糊 | 排开要错峰（复印感），吸回要同步（收束感）——节奏不对称是设计 |
+| 停留 | 32f，期间相机极缓推近 2% + 纵队轻微视差漂移 | 停太短数不清"有很多个"，完全静止又是死帧 |
+| 合体 | 主卡 sin 单脉冲 1.06x + 一次强调色描边光（14f 衰减）；同帧镜头位全亮、计数器回弹 | 吸回无弹跳读作淡出；弹跳=质量证据 |
+| 计数 | 左下 260px「×N」，每弹出一个克隆滚一格（5f，出场格上移淡出 + 速度竖向虚化） | 计数让"规模"从画面变成数字；滚动格不要 overflow 裁切，会把泛光裁出方框 |
+
+## 已知坑
+- demo 用手搓的 video-shotcraft 渲染卡（lime 暗场）调校——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 克隆体必须从后往前渲染保证遮挡正确；透明度 ≤0.005 条件卸载
+- 同批 3D 渠道另两条（厚板转台淘汰、走廊改改再看）——纯陈列型
+  3D 运镜相性存疑，本卡过墙靠的是"排开-吸回"的叙事动作，
+  实战别退化成静态纵队陈列
+- 声音：排开一串细"啪"错峰，吸回一声上扬 whoosh，合体一声实"咚"
+
+## 参考实现
+demos/ui-entrance/cloner-depth-echo/
+（ClonerDepthEcho.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/deck-deal-flyin.md

@@ -0,0 +1,45 @@
+---
+name: deck-deal-flyin
+一句话: 暗色石墨桌面上的实体牌堆特写环绕开局，灯从牌堆亮到旁边的页面板，一摞卡像发牌一样硬加速甩进网格，相机追着发牌升起后仰、落在整块满板的跑道式俯瞰上定格
+适用: 展示"内容量大/源源不断汇入"的列表页与卡片墙；建立信息密度的第一印象
+时长: 150f（约 5s：0–36 牌堆特写 + 预备，36–~101 发牌，108–150 满板 hold）
+能量: 高（节奏爬升段主力，不放开场第一镜）
+---
+
+## 意图
+先给悬念（这一摞是什么？），再给答案（是几十个项目，它们自己飞进页面各就各位）。观众要感受到"东西源源不断地涌进来"，每张卡带着急迫感砸到位。
+
+## 动效核心
+- 前半（pile-orbit-open，可选）：所有卡叠成有物理高度的实体牌堆，放在页面板旁的暗色拉丝石墨桌面上，顶光只打牌堆，相机侧斜特写绕堆环绕；拉远时"灯"从牌堆处以柔边光圈把暗着的页面板照亮——页面板始终是摆在暗桌上的一块展板，四周暗场贯穿到尾帧
+- **预备拍（anticipation，借鉴迪士尼法则 2）**：首张出牌前给一拍段落级预备——牌堆整体微下压 + 顶卡向出牌反方向回拉，观众的眼睛先被引到牌堆再看发牌。预备只做段落级一次，**不逐卡加**（逐卡预备会拖垮 R2 的硬加速节拍）
+- 后半（deck-deal）：26 张卡从牌堆按阅读序发向网格目标位，出牌间隔硬加速收缩；单卡飞行带 z 弧顶、过冲 settle、落地 press 回弹（settle/press 即法则 5 的 follow-through——快停配缓冲，砍掉读作硬冻结）
+- 相机追着发牌往板尾走（越来越快），同时升高、后仰、侧转，落在一张跑道式俯瞰：整块板沿对角线伸向远处、26 张卡全部在画，远端压暗做景深；满板后静止 hold（> 0.5s，只留 1.5% 极缓推近），左下升起标语 + mono 计数行（计数跟着落地张数跳）。收尾停顿期各层不同帧停稳——卡体先落定、阴影收敛滞后 ~3f、残影最后消散（拖拽层级，借鉴法则 5；全要素同帧冻结读作机械）
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| orbit 环绕 | 相机关键帧走单调三次 Hermite 样条逐帧展开（关键帧处速度连续，无顿挫）。帧 0→30，rotX 48/rotY −30/rotZ 9/zoom 1.9 绕到 rotX 42/rotY 24/rotZ −6/zoom 1.8，persp 1100 | 特写四件套缺一不可：侧面倾斜角+可感知高度+orbit+反差深色材质（Q7，用户逐项点名） |
+| 堆叠高度 | STACK_STEP=3px 物理层高 × 26 张 → 顶卡 z≈78px；姿态抖动 px/py 按 `(((k*7)%9)−4)*2` 确定性公式 ±8px、rotZ ±3° | 抖动必须确定性伪随机（硬规则：渲染必须可复现），真随机会渲染间抖动 |
+| 石墨桌面 | 4 层叠加：随拉远扩大的顶光 radial + 104deg 宽幅镜面高光带 + 确定性 feTurbulence 各向异性拉丝纹小图平铺（baseFrequency 0.0018×0.62，alpha 0.4）+ 115deg 冷灰渐变；平面向外扩 4000px、远处柔边隐进暗场。页面板（截图内容区 x 352–1568 + 纸面延长）开场被 0.88 暗层盖住，34→64f 以牌堆为圆心柔边光圈揭开；落进未照亮区域的卡用同一公式压暗 | 别再整层淡出金属换成全屏白纸——暗/亮反差是这镜的质感来源；拉丝纹在 0.5x 俯瞰下对比要压低，否则出摩尔纹 |
+| 预备拍 | 首发 cue 前 10f（26→36）：牌堆整体下压 48px（约堆高六成）+ 顶卡向出牌反方向回拉 30px，缓动 easeOut，首发瞬间释放 | **幅度必须过肉眼阈值**：4px/2px 初版用户实测完全无感，放大 12 倍（48/30px）才裁决通过（判例 2026-07-09 进化轮 #2）——渲染后自查"不逐帧能否看出蓄力"，看不出等于没做；帧预算从 orbit 尾段挪，不挤占发牌段 |
+| 发牌节拍 | 第 k 张 cue = 36 + 4k − 0.0792·k(k−1)，间隔 4f 收缩到 0.2f | 均匀间隔立刻显得机械；匀加速不够狠也被否——要"hard-accelerating"级别（R2/B3） |
+| 卡量 | 10 真卡 + 16 extras = 26 张；网格向下扩 5 行、纸面延长 2036px | 卡不够多涌入感不成立——宁多勿少；extras 落进真实扩展格位，不悬浮（Q9） |
+| 单卡飞行 | deal 8f（bezier(0.3,0,0.2,1)，z 弧顶 +110px sin、scale 峰值 1.06）+ settle 4f（bezier(0.3,0,0.25,1.15) 轻过冲）+ press 0.996→1 回弹 2f | 落地要弹必须 y1>1 的 bezier；settle+press 合计 6f ≈ 飞行 8f 的 30%——快停配足缓冲（法则 5 比例）；落定后强制 identity transform 防斜板亚像素漂移 |
+| 收尾拖拽层级 | rest 段内分层停稳：卡体 press 回弹结束即锁定，落地阴影 `0 32px→0 2px` 收敛滞后卡体 2–4f，飞行残影 opacity 尾梢再拖 3–5f 消散 | 借鉴法则 5 的 drag hierarchy（根→主→次级错帧 2–4f）；0.5s rest 静止判例不变——层级错帧发生在 rest 段头部，rest 末端全部锁死（模式已沉为 assets/lib/helpers/motion.ts lagged） |
+| 运动模糊（单卡） | 飞行中 5% 路径滞后 blur(6px) 残影，opacity 0.25·(1−t) | ghost 残影比真 motion blur 便宜且够用——单卡层面维持此方案 |
+| 运动模糊（相机） | 追逐 scroll 等 ≥30px/f 的快速运镜段用 `@remotion/motion-blur` 的 `<CameraMotionBlur shutterAngle={180} samples={10}>` 包镜；用 `<Sequence>` 把包裹范围切到快速段起点，慢速特写段（<10px/f）不包 | 30fps 下相机每帧跳 50–70px 会频闪，快摇拖影是电影摄像机的物理本能；shutterAngle 越大拖影越长（>270 发糊），samples 按渲染预算调（每 +1 约 +1 倍渲染时间）；整镜全包会把慢速 orbit 段的 1px 级细纹理（拉丝金属）采样抹软——只包快速段；借鉴 Remotion 官方生态非用户判例（2026-07-11 进化轮 #8） |
+| 追逐 + 升起 | 锚点 f62 正视板顶（zoom 0.8，rotX 22）→ f86 板中（zoom 0.56，rotX 38，rotZ −10）→ f110 跑道俯瞰（zoom 0.5，rotX 52，rotY −6，rotZ −26，persp 3300，屏幕右移 300px 给左下标语让位）→ f150 zoom 0.508 | persp 要随后仰同步加大（1100→3300），否则近端越过相机平面穿帮；满板后静止是用户逐字要求（R2），hold 只许极缓推近 |
+
+## 声音
+orbit 拉远+首批发牌钉 whoosh-big（模板片钉在 f308），发牌加速段钉 whoosh-fast（f340/356）。连发落位音防机枪感三招：双样本交替、音量阶梯递减、间隔跟随动画曲线加速——密到糊成一片时让声音淡出成一条 swoosh，不逐卡配音（S2）。
+
+## 已知坑
+- 抽象 flood 式多轮不收敛，换"发牌"物理隐喻一轮通过（R2/B3）——群体运动先找物理隐喻再写代码
+- 卡纹理必须真实页面元素切片（Q1），手搓假卡一眼假；extras 复用真卡切片错位摆放
+- 全部同时飞读作爆炸，错峰递加速是灵魂；前半 orbit 若砍掉，发牌起点要另给"牌堆从哪来"的交代
+- anticipation/follow-through 手法借鉴自迪士尼 12 法则（pixel2motion skill 内置提炼版）；预备拍幅度已有用户判例（2026-07-09："OK能看出来了"，此前两档小幅度均无感）；拖拽层级错帧仍是默认建议——与 R2 判例冲突时（如用户要求更快更硬）判例优先
+- 教科书比例（预备 = 主动作 20–30%）在拉远机位下产出的像素位移过小——**先算像素再算比例**，宣传片观众看的是全景不是特写
+- `<Sequence>` 重定基帧号 + CameraMotionBlur 内部 Freeze 会让 PageCam 采样错帧（横向错模糊穿帮）——绝对帧编排的镜头给 PageCam 传 `frame` prop 还原绝对帧（lib 组件已支持）
+
+## 参考实现
+demos/ui-entrance/deck-deal-flyin/DeckDealFlyin.tsx（原 template/src/aifl/live/SceneFlyIn.tsx 0–113 段）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/doc-park-left-pill-deal.md

@@ -0,0 +1,62 @@
+---
+name: doc-park-left-pill-deal
+一句话: 文档不淡出而是向左滑出只露约 35% 宽并微缩到 0.92，右侧按旁白节奏慢速发牌三张白底描边药丸（outBack 弹入），每张落定后其下方字幕逐词加深、下一张到来前整句淡出，左侧文档全程极缓慢自动滚动保持"正在被读"
+适用: 旁白驱动的"分析结论逐条给出"段落；文档理解、推荐理由、审阅意见类产品的核心说明镜头
+时长: 约 5.8s（174f@30fps）
+能量: 低（慢发牌节奏，全片无峰值；靠自动滚动维持活性）
+---
+
+## 意图
+结论要一条一条给，观众才记得住。但如果把来源文档淡出，结论就变成了空中楼阁——观众
+不知道这些话从哪来。这张卡的解法是**让来源留在画面里**：文档靠左驻留只露一截，还在
+缓慢滚动（说明它正在被读），右侧的每条结论都是从这份文档里长出来的。发牌节奏刻意慢，
+是为了给旁白留出说完一句的时间。
+
+## 动效核心
+- 驻留（park）不是淡出：`seg(t, 0.06, 0.24, E.inOutCubic)` 驱动
+  `translateX(0→-55%) scale(1→0.92)`，`transform-origin: 0% 50%` 让缩放以左边缘为锚，
+  文档缩小时不会离开画框左侧——最终只露约 35% 宽
+- 常驻自动滚动：`translateY(-t * 120)` 连续匀速（≈0.7px/f），内容比容器长 140px 以上。
+  旧写法 `-(t*3 % 1) * 40` 取模，非周期内容每 1/3 片长整页回跳 40px，肉眼可见，已弃用
+- 慢发牌：三张药丸起点写死在 `T0 = [0.26, 0.48, 0.70]`——间隔 0.22（约 38f / 1.27s），
+  这是一句短旁白的长度，不是 UI 常规的 stagger
+- 每张药丸两条曲线并行：`o = seg(t, f, f+0.035, E.outQuad)` 管透明度（快，约 6f），
+  `b = seg(t, f, f+0.062, E.outBack)` 管 `translateY(14→0) scale(0.94→1)`（慢，约 11f
+  且带过冲）——先看见、再落定，比单曲线更有"接住"的手感
+- 字幕四段编排：起点 `cs = f+0.05`（药丸落定后约 3 帧），`show` 用 0.02 的窗快速出现，
+  `inn` 逐词加深摊在 `(ce-cs)*0.7` 上，`ce` 是下一张的起点减 0.03（末张 ce=0.98），
+  `out` 在 `ce-0.05→ce` 淡出——每句字幕在下一张药丸入场前就已清场，画面永远只有一句
+- 药丸终态是静态列表（`top = 54 + k*48`），三张全部落位后一直留在画面上，读作
+  "结论清单已成形"
+- 依据联动：每张药丸落定后，文档里对应的依据句被荧光笔自左向右划出（f+0.06→0.13），
+  一条强调色细线从该句行尾连到药丸左缘（f+0.04→0.11 draw-on），随该句字幕退场淡出
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 发牌起点 | `T0 = [0.26, 0.48, 0.70]`，间隔 0.22（≈38f） | 间隔就是旁白句长；压到 0.12 以下字幕的"逐词加深"来不及走完，读作字幕闪一下就没了 |
+| 驻留窗 | 0.06→0.24（inOutCubic） | 必须在首张药丸（0.26）之前收住；重叠会出现"文档还在滑、药丸已在发"的浑浊 |
+| 驻留幅度 | `translateX -55%` + `scale 0.92`，露约 35% | 露太少（<25%）文档变成装饰失去"来源"语义；露太多右侧放不下 172px 宽的药丸 |
+| 药丸透明度窗 | 0.035（≈6f，outQuad） | 比位移窗短是有意的——先实后稳；两窗等长会读作普通淡入 |
+| 药丸位移窗 | 0.062（≈11f，outBack），y 14→0、scale 0.94→1 | outBack 的过冲是"发牌落桌"的手感；换 outCubic 会变成平淡的浮上来 |
+| 字幕延迟 | `cs = f + 0.05`（≈9f） | 药丸落定（0.062）之后才起字幕；提前会出现字幕先于结论出现 |
+| 字幕加深行程 | `(ce-cs)*0.7` | 占该句可见时长的 70%，末 30% 是全实态的静置阅读时间；调到 1.0 则字幕刚读完就被淡出 |
+| 自动滚动 | `-t × 120px` 连续匀速 | 5.8s 上约 0.7px/f，是"正在读"的暗示级速度；>3px/f 会抢注意力变成滚动展示 |
+
+## 已知坑
+- 自动滚动是连续位移而非取模循环（取模只有在内容本身严格周期时才不回跳）；改时长或
+  行程时要保证文档内容比容器长出至少整段行程，否则末段会滚出空白
+- 末张字幕的 `ce = 0.98` 意味着它在 0.93→0.98 淡出，末帧只剩三张药丸没有字幕。若要
+  末句留到底，把末张的 `ce` 改成 >1 并去掉 out
+- 药丸位置写死为 `left:214px, top:54+k*48`、宽 172px，是 480 宽画布下与驻留后文档
+  （露出约 87px）配套的一组数字。改文档驻留幅度必须同步改 PX，否则两者重叠
+- 三条药丸文案（demo 里是 video-shotcraft 宣传片简报推荐的三张镜头卡 Crash Zoom / Deck Deal / Logo Sting）与三句字幕都是示意，且字幕
+  长度直接影响"逐词加深"读起来快慢——换真实文案后要按新句长重调 `inn` 行程
+- 药丸数写死为 3（`T0` 的长度）。加到 4 条时间就不够：末张起点会超过 0.9，字幕根本
+  走不完；4 条以上应考虑缩短单句而不是硬塞
+- 字幕的 `ce` 依赖 `T0[k+1]`，改任一张的起点都会连带改变前一张字幕的可见时长——这
+  是有意的联动（字幕永远填满到下一张之前），但调参时要意识到不是独立参数
+
+## 参考实现
+demos/ui-entrance/doc-park-left-pill-deal/
+（DocParkLeftPillDeal.tsx）

package/lib/motion/shotcraft/upstream/references/shots/ui-entrance/draw-svg-trace.md

@@ -0,0 +1,55 @@
+---
+name: draw-svg-trace
+一句话: 描边生长圈注——一条带笔头的墨线沿元素轮廓跑一圈把它"画"出来，闭合瞬间闪黑交棒、内容淡入；同套路可给标题画下划线
+适用: 单个卡片/图表/标题的被点名入场；元素级手法（整页级蓝图描线归 wall-reveal-moves B 式）
+时长: 132f（预告 10f + 描边 40f + 闪黑交棒 16f + 下划线 18f + hold 40f，约 4.4s）
+能量: 中
+标签: typography
+---
+
+## 意图
+"画出来"是纸墨审美里最顺手的入场隐喻：元素不是飞进来也不是淡进来，
+而是被一支看不见的笔当场描出来。库内 wall-reveal-moves B 式已有整页
+蓝图版（全屏线框逐段画+区域点亮），本卡是它的**元素级特写版**——
+一条线、一个主体、一次闭合，笔头可见、方向可读，适合"接下来讲它"
+的点名时刻。第二用法是标题下划线生长：同一套路 18f 短版，给重点词
+一笔手绘强调，与马克笔审美 token 天然同族。
+
+## 动效核心
+- **免测周长**：SVG rect/path 设 `pathLength={1}`，strokeDasharray="1"，
+  dashoffset 1→0（40f Easing.inOut(cubic)）——不用 getTotalLength
+- **笔头**：同一路径再叠三段渐细短 dash（0.04/6.4px → 0.024/8px → 0.011/9.6px），dashoffset = 笔头长 − p，
+  天然跑在最前；再加一颗按圆角矩形弧长精确定位的实心笔尖（带落影）；
+  没有笔头就只是"边框在变长"，有笔头才是"有人在画"
+- 预告：开场 0–12f 四角先长出裁切标记（印刷对位线，错峰 2f），底下是一层中心清晰、四周隐去的绘图纸点阵——
+  第 1 帧就有画面，观众先知道"这里要画一个东西"；闭合时裁切标记外弹 22px 并淡出
+- 闭合闪：50–52f 描边冲纯黑 + 6→11px 加粗，52–58f out 回落
+  ——白底上加深加粗，不用发光（判例）
+- 交棒：56–66f 描边层淡出、元素自身发丝边淡入；50f 起卡底上墨、卡片从贴地升起（阴影长出来），
+  内容自上而下 3f 错峰由虚到实 + 上浮，柱图错峰 1.5f 从基线长出——闭合即"画完了"，内容跟着"上色"
+- 第二用法：74–92f 给重点词「100%」画一笔朱红马克笔下划线（略带弧度的手绘路径，笔头跟随），画完常驻
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 描边速度 | 一整圈 40f（10→50f，inOut cubic 起收有呼吸） | <28f 读不出"在画"，>60f 读作加载中 |
+| 主线 / 笔头 | 主线 6px；笔头三段渐细最粗 9.6px、笔尖 r 7.5 | 笔头≤主线粗细就消失在主线里 |
+| 闭合闪 | 2f 冲黑 + 加粗到 11px，6f 回落 | 没有这一下，"画完"没有句号 |
+| 主体尺寸 | 1120×660、圆角 28（描边 rx 同值） | 主体占画宽 ~58%，描边一圈才有"画了一个大东西"的分量；描边 rx 必须等于卡片圆角 |
+| 下划线版 | 18f out cubic 单向生长，12px 朱红、路径带 ±5px 手绘弧度，画完常驻 | 用在单个重点词；一屏 ≥2 条读作装饰线 |
+| 收尾 | 交棒完成后 hold 40f（92→132f），只留 0.9% 极缓推近 | R1 |
+
+## 已知坑
+- demo 用手搓的 video-shotcraft 渲染报告卡（paper 纸墨 look，「Cuts on the beat / 100%」+ 逐镜头能量柱 + 标志字标署名）调校——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 wall-reveal-moves B 式（整页蓝图描线）同族互斥：同片二选一，
+  都上读作重复报幕
+- 描边路径必须与元素真实轮廓吻合（圆角 rx 一致）——线画的是 14px
+  圆角、元素是 8px，交棒瞬间错型穿帮
+- 真实素材上内容淡入别抢在闭合前：线还没画完内容先出来，"画"的
+  因果就断了
+- 一次点名画一个主体；同屏多元素排队各画一圈读作加载动画
+
+## 参考实现
+demos/ui-entrance/draw-svg-trace/
+（DrawSvgTrace.tsx）