dsh-drawai 0.3.4 → 0.4.0

package/lib/motion/shotcraft/upstream/references/shots/effects/riso-print-hits.md

@@ -0,0 +1,49 @@
+---
+name: riso-print-hits
+一句话: 套印错位冲击帧——riso-misregistration-hit 单发：标题撞停瞬间裂成双色 riso 印版，抖两下"啪"地套准
+适用: 标题/卡片的命中强调，纸墨审美版的"故障闪"；全片 1–2 次的单发高潮
+时长: 4s（120f，单发）
+能量: 高
+标签: typography
+---
+
+## 意图
+RGB 色散故障闪（impact-feedback C 式的一部分）是荧光屏语言，与纸墨
+调性相克。这张卡给出印刷版平替：元素裂成两份单色 riso 印版（demo：荧光粉 × 蓝；
+multiply 油墨感而非 screen 荧光感，两版套准时叠成深色墨），
+像 risograph 没对准版，抖几下
+"啪"地套准——同样的冲击力，介质想象完全换成纸上油墨。单发：
+撞停瞬间裂版、震荡衰减、硬切套准，给一次命中盖章。demo 是一张 video-shotcraft 的
+双色 riso 宣传海报（「CRAFT IT / LOUD.」+ 三栏卖点，圆章中心是单色版镜刻标志）。
+
+## 做法
+| 式 | 做法 | 适用 |
+|----|------|------|
+| misregistration-hit 单发 | 标题 8f 撞入撞停，裂两版反向错 ~40px，44f 衰减震荡后硬切套准 + scale 脉冲 + 「ON REGISTER」圆章盖下 | 全片 1–2 次的命中盖章；标题/大字的到位一瞬 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 双版 | 两色 riso 油墨：荧光粉 #ff4fa3 + 蓝 #1f5fc4（套准叠成深紫）。`mix-blend-mode: multiply` 叠在再生纸（#f3eee2 + 静态纸纤维/油墨颗粒）上，位移反向；套准即两版归零重合 | multiply 叠出的重影就是"油墨没对准"；screen 叠加立刻变荧光故障；两版选互补色相、套准后叠成近黑最好，别用纯灰（读作阴影） |
+| 错位包络 | `offset = A·cos(2πt/18)·exp(-t/60)`，A=(20,8)px 两版反向（300px 标题）；帧 72 硬切归零 | 命门：套准是**硬切跳变**不是渐收——衰减到 ~11px 残余时啪地归零才有"啪"；纯渐收读不出套准一拍 |
+| 撞入 | 8f Easing.in(cubic) 从画外撞停，命中帧即裂版 | 裂版必须与撞停同帧——晚 2f 就读作两件事 |
+| 套准脉冲 | 归零帧 4f scale 1.03→1；同帧圆章 scale 1.5→1 盖下；命中帧整页 1.2% 顿挫 10f 回落 | 盖章的一拍；省略则套准无重量 |
+| 作用域 | 错版只作用标题，背景（太阳 / 版记 / 信息栏）保持套准 | 整画面全裂读作故障而非印刷 |
+| 收尾 | 套准后 ≥40f 真静止 | R1 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- **错位幅度可感性判例（本批实渲）**：词汇表原案 ±5px 在 1920 宽画面
+  正常速度下肉眼几乎不可见——单版 16px/总分离 32px 起步才可感（200–300px 大标题按 20px/40px）；
+  幅度存疑时做极端版给用户看（可感性优先）
+- 本卡与 impact-feedback C（负片冲击帧）语义重叠——纸墨调性片子用本卡、
+  游戏/动漫调性用 C 式，同片不并用（P4）
+- 错位方向一横一纵混合（x 为主 y 少量）更像没对准版；纯横向读作
+  左右晃动
+- 300px 大字配 −0.045em 负字距时，相邻字形的横笔可能恰好相接（如 CRAFT 的 F→T 顶横），
+  两边抗锯齿叠出一条发丝亮缝——给前一个字单独再收 ~0.01em 让两笔重叠即可
+
+## 参考实现
+demos/effects/riso-print-hits/
+（RisoMisregistrationHit.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/scan-bracket-sweep.md

@@ -0,0 +1,50 @@
+---
+name: scan-bracket-sweep
+一句话: 文档弹到中央，四角落下 L 形取景括号，一条扫描光带拖着渐变尾迹在文档上往复扫 5 趟——文档全程静止，只有光在读它
+适用: "正在解析/校验这份内容"的过程镜头；文档类产品的能力演示；上传→分析链路的中段
+时长: 约5.0s（150f@30fps）
+能量: 中低（机械、克制，节奏全在往复扫掠的呼吸上）
+---
+
+## 意图
+让观众看懂"这份东西正在被机器逐行读过"。取景括号先把目标框住（宣布检查
+对象），扫描光带再往复走完全篇（宣布检查过程）。命门是**文档本身完全静止**：
+一旦文档也在动，观众就分不清是"被检查"还是"在加载"。
+
+## 动效核心
+- 文档 `seg(0→0.11, outCubic)` 从 scale 0.86 弹到 1，opacity 走 `dp*3`
+  提前满亮，落位比缩放早——先"在了"再"稳了"
+- 四角 34px 的 L 形括号按 `i*0.022` stagger 依次落位，各 0.055 走完，
+  从外侧沿对角带 8px 位移收进来（overshoot 缓动，约 8% 轻过冲再落定）
+- 扫描窗口 `t 0.17→0.95` 严格 linear 切成 5 趟，趟内 `inOutSine`
+  两端慢中间快，末尾留 12% 完全停顿（`local=(raw-pi)/0.88`）
+- 光带 = 1.2px 靛蓝光芯 + 10px 对称柔辉 + 拖尾；拖尾最长 82px、`SCAN .2→0`
+  正片叠底，长度随扫描速度伸缩（趟末停顿处收成 0，换向不跳）；方向随 `dir`
+  翻转：下行时挂在光带上方、上行时挂在下方，渐变同步反向
+- 光芯经过的表格行被轻微照亮（行底 SCAN 9%，高斯衰减）——光在读，文档不动
+- 整条光带裁在与文档同 10px 圆角的 `overflow:hidden` 层里，
+  `0.16→0.20` 淡入、`0.93→0.99` 淡出
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 文档弹入 | scale 0.86→1，t 0→0.11 outCubic | 起始值低于 0.8 就成了"从远处飞来"，弹入要小幅度才像 UI |
+| 取景括号 | 臂长 34px、圆头描边 1.6px、外扩 −7px；stagger 0.022 / 各 0.055 | 四角同时出现读作静态边框；差 0.022 就够读出"依次落下" |
+| 扫描趟数 | PASSES=5，窗口 t 0.17→0.95 linear | 3 趟不够读作"往复"，7 趟以上在 5s 内每趟太快 |
+| 趟内缓动 | inOutSine + 末尾 12% 停顿 | 停顿是"看清了这一趟"的换气位；去掉就成了匀速来回摆 |
+| 光带 | 1.2px 光芯 + 柔辉 + ≤82px 拖尾 SCAN .2→0（multiply） | 线太粗（>4px）读作遮罩边缘而不是光；拖尾用黑灰会读成脏污 |
+| 拖尾方向 | 下行 top:−tail / 上行 top:0，渐变一并翻转；tail 随速度 | 只翻其一 → 拖尾跑到运动前方，读作"光在往回吸"；定长拖尾换向时会整块跳到另一侧 |
+| 裁切层 | 与文档同 10px 圆角 overflow:hidden | 漏到文档外就是"扫画面"不是"扫文档" |
+
+## 已知坑
+- 光带必须裁在文档 bbox 内，且圆角与文档一致——漏出一点就丢掉"扫描
+  这份文档"的语义
+- 拖尾的 `top` 和 gradient 方向是两处独立写法，改扫描方向时必须同改，
+  漏一处就出现"尾迹在前"的反物理观感
+- 括号的 34px 臂长与 −7px 外扩是按 300×178 的文档尺寸配的；换真实截图
+  要按新尺寸重算，臂长超过短边 1/4 就压住内容
+- 两个颜色变量：INK（括号 + 正文）与 SCAN（光芯 + 柔辉 + 拖尾 + 行照亮），换肤只改这两个
+
+## 参考实现
+demos/effects/scan-bracket-sweep/
+（ScanBracketSweep.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/scanline-annotate-focus.md

@@ -0,0 +1,53 @@
+---
+name: scanline-annotate-focus
+一句话: 一条扫描线自上而下匀速掠过已存在的页面，越过哪块区块的下缘，哪块就被四角取景框从外扩处弹簧收拢对准（一次过冲），随后贴出一枚逐字打出的机器标签，顶部状态行同步计数 00/06→06/06
+适用: "AI 正在读你的页面/品牌"的分析镜头；设计系统/品牌规范的拆解介绍；产品能力的自我说明段
+时长: 约5s（150f@30fps）
+能量: 中（机械冷静，节奏由扫描线匀速推动，标注是节拍点）
+---
+
+## 意图
+把"分析"这件抽象事做成可见的因果链：扫描线走到哪，那块就被框住、被
+命名。观众读的是"机器的视线"，所以扫描线必须匀速、标注必须严格滞后于
+扫描线过境——**先扫到再弹框**，顺序一旦错乱就变成了预先编排的动画。
+
+## 动效核心
+- 两套颜色严格分工：**品牌色**（demo 为赤陶 `#C4552D`）只在页面内容里，**机器色**（钴蓝 `#2B4FD8`）
+  只给扫描线 / 角标 / 标签 / 状态行——观众一眼分得清"页面本身"和"机器的视线"
+- 页面（demo 为 video-shotcraft 官网：镜刻标志 + 字标、H1、样片封面、CTA、色板）装在 1560×840 浏览器窗里（两层软阴影），状态行在窗外上方；全程 1.000→1.035 极缓推镜
+- 扫描线 6→80f **严格匀速**走窗内 y −20→860：3px 光芯 + 身后 140px 渐隐淡蓝洗色与 18px 点阵余晖；
+  窗框两侧各一枚随线滑动的三角游标，左侧读出当前 `Y 0412`
+- 触发帧由 bbox 反算：`ft = frameAtY(y + h)`（扫描线越过 bbox **下缘**那一帧），按下缘排序后钳制
+  最小间隔 4f；demo 实测 LOGO 19f · NAV 23f · H1 48f · CTA 68f · HERO 72f · PALETTE 77f
+- 取景框：四个 L 角（3.5px 圆头）从外扩 76px 处按 `spring(damping 15, stiffness 210)` 收拢到 bbox
+  （一次可见过冲，略收进 bbox 再回）；臂长 40→26px 晚 3f 收一档（跟随）；`ft+3→+6` 框内钴蓝对焦闪
+  （填充 0.075 + 2px 内描边）`+6→+18` 落
+- 标签 `ft+5` 出现：设计工具式钴蓝底白字小签（高 50、32px 等宽、类目 750 亮 / 细项 500 · 78% 白），
+  文字 ~2.2 字/帧逐字打出、签条宽度随字长出（右缘略领先）+ 白色块光标，8px→0 上浮
+- 状态行实时数已触发数 `SIGNALS 0n / 06` + 扫描进度条；最后一块触发后 8f 切 `BRAND READ`（转机器色），
+  之后 ~60f hold 是完整海报
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 扫描线 | 74f 匀速，窗内 y −20→860 | **零缓动**：加 ease 就读作"有人在拖进度条"；60f 以下标签来不及打完就扎堆 |
+| 触发换算 | ft = SCAN0 + (y+h−Y0)/(Y1−Y0)·(SCAN1−SCAN0) | 改扫描窗口只改 SCAN0/SCAN1/Y0/Y1 四个常量，触发自动跟随 |
+| 最小间隔 | prev + 4f | 同一行的 LOGO / NAV 会同帧弹；钳制后才逐个读得清 |
+| 取景框收拢 | 外扩 76px → 0，spring damping 15 | 按像素外扩而非按比例缩放：大小目标收拢量一致；外扩 <40px 看不出"对准"动作 |
+| 角标 | 臂长 40→26px、描边 3.5px | 臂长超过目标短边 1/3 就变成完整边框，丢掉"取景"语义 |
+| 对焦闪 | 填充峰值 0.075 | 超过 0.12 在亮底上成一块灰盒，读作"选中高亮"而非对焦确认 |
+| 标签 | ft+5 起、~2.2 字/帧、32px 等宽 | 滞后 5f 是"框稳了才命名"的因果；签条一次性画满宽再打字会露出空蓝条 |
+| 计数行 | 按 fired 实时统计，30px 等宽 | 写死时间轴的计数一改 bbox 就对不上；必须实时数 |
+
+## 已知坑
+- **扫描线触发时刻与目标 bbox 强绑定**：换页面内容后 targets 的 `x/y/w/h` 要重测，
+  bbox 是手动量的（不是自动量元素），留边约 12–16px
+- 标签放置四选一（`right / above / below / belowRight`），宽度按等宽字数估算 `CHAR_W = 0.6em`；
+  词变长先查会不会压到相邻模块或顶出窗外——H1 这类宽目标标签放上方，右上角目标的标签右对齐放下方
+- 亮场页面上扫描线和角标要用深而饱和的机器色；浅色辉光线在亮底上几乎不可见
+- 与 `scanline-assemble-flyin` 分工：那张是"扫到即装配"（页面从空到有），
+  本卡是"扫到即标注"（页面已存在，只做分析）
+
+## 参考实现
+demos/effects/scanline-annotate-focus/
+（ScanlineAnnotateFocus.tsx）

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

@@ -0,0 +1,53 @@
+---
+name: scanline-assemble-flyin
+一句话: 页面开场是一张只有网格与虚线槽位的蓝图画板，一条亮扫描线自上而下掠过；扫到每个槽位，该处组件就从画外飞入过冲贴合，带方向性残影模糊与落位咬合角标——扫完整页恰好装配完成
+适用: "页面自己生成"的开场；AI 建站/自动排版类产品的核心演示；从空白到成品的能力叙事
+时长: 约5.2s（156f@30fps）
+能量: 中高（扫描线是稳的，但每次组件飞入都是一个爆点，密度递进）
+---
+
+## 意图
+让"页面被生成"这件事有一个可信的施工顺序：扫描线是施工进度条，
+组件从画外飞进来贴合是施工动作。关键是**扫完那一刻恰好装完最后一块**
+——扫描线提前收工或组件拖尾都会让"扫描驱动装配"的因果关系散掉。
+
+## 动效核心
+- 第 1 帧就是完整的"施工图"：全屏蓝图网格（24px 细线 α.045 + 120px 主线 α.085）、1640×860 画板虚线外框
+  与宽度标注、每个组件的虚线槽位（带 `H1 820×250` 类小标）——观众先看到"要装什么、装在哪"
+- 扫描线 8→92f **严格匀速**走画板 y −20→880：白芯 + 电光蓝三层辉光，两端各出画板 60px 渐隐；
+  线身后 180px 网格被照亮，且**页面底色被"刷"出来**（画板表面 mask 跟着扫描线下移）
+- 落位帧由槽位下缘反算：`land = frameAtY(y + h)`，按下缘排序钳制最小间隔 4f；飞行 14f **提前起飞**，
+  组件与扫描线同时到位。demo 实测 NAV 19f · BADGE 29f · H1 55f · BODY 66f · MEDIA 75f · CTA 79f · STATS 88f
+- 7 个组件各有画外起点：导航自上（0,−260），徽章 / H1 / 正文自左（−620…−980），媒体卡自右（+900,+80, 6°），
+  CTA / 数据行自下（+420…+460）；`EASE.overshoot` 过冲 ~8% 贴合，旋转 ±2–7° 同步归零
+- 运动中按位姿中心差分求速度，`SpeedBlur` 沿飞行方向拖影（0.32×速度、≤18px），落位 4f 后清零
+- 落位：槽位虚线 4f 内消失；四角电光蓝 L 角（臂长 22px）从外扩 20px 咬进到 10px，`land+1→+4` 亮、`+5→+14` 收；
+  满宽导航不加
+- 状态行 `BLOCKS 0n / 07` + 秒表实时走；最后一块落位后切 `✓ BUILT`、秒表定格，蓝图网格退到 30%、
+  媒体卡（银河样片镜头）亮起一档，之后 ~50f hold
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 扫描线 | 84f 匀速，画板 y −20→880 | 收工时刻要略晚于最后一块落位，才读作"扫完即装完" |
+| 触发换算 | land = SCAN0 + (y+h−Y0)/(Y1−Y0)·(SCAN1−SCAN0) | 改扫描窗口只改四个常量；飞行时长 FLIGHT 是提前起飞量，去掉就变成"扫过之后才动" |
+| 最小间隔 | prev + 4f | 下缘接近的 MEDIA / CTA 会同时落；钳制后才有"一块一块"的密度 |
+| 飞入位移 | 画外 260–980px，按组件所在方位定 | 位移小于 200px 读作"抖一下就位"，不是从画外来 |
+| 飞入旋转 | ±2–7° | 超过 12° 就读作"翻滚"，贴合时不服帖 |
+| 飞入缓动 | EASE.overshoot，14f | 过冲是"吸附贴合"的手感；纯 ease-out 就成了滑入 |
+| 残影模糊 | 方向性 SpeedBlur 0.32×速度、≤18px，落定清零 | 各向同性 blur 读作失焦而不是速度；不清零会留一层永久糊 |
+| 落位角标 | 外扩 20→10px、臂长 22px，3f 亮 / 9f 落 | 角标是"咬合"的听觉替代品；整圈描边闪框读作调试框、且 7 次群发违反 Q4 |
+
+## 已知坑
+- **触发时刻与 PLAN 里的槽位 box 绑定**：换页面模板后每个组件的 box 要重测，否则组件在扫描线到达前就飞入
+- 组件在 `Fly` 里以槽位为原点绝对定位；角标层是组件内部的 SVG（overflow:visible），
+  组件自身若 `overflow:hidden` 会把外扩角标裁掉——媒体卡的裁切放在内层
+- 页面底色"刷出"用的是画板表面的 linear-gradient mask（跟扫描线 y），蓝图网格是另一层；
+  两层都随扫描线走，别把网格也 mask 掉，否则扫描线下方会变成死黑
+- 与 `scanline-annotate-focus` 共用"扫描线即因果"的逻辑；两张卡可以串联（先装配、后分析），
+  但扫描线要换向或留空档，否则读作重复
+- 页面内容为 video-shotcraft 的落地页（镜刻标志 + 字标导航、「Shoot the / launch film.」H1、样片镜头卡），强调色（电光蓝 / 青）取自 LOOKS.midnight，换肤改 L 即可
+
+## 参考实现
+demos/effects/scanline-assemble-flyin/
+（ScanlineAssembleFlyin.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/slam-entrance-moves.md

@@ -0,0 +1,55 @@
+---
+name: slam-entrance-moves
+一句话: 高能砸入三式——kanada-perspective-snap 金田透视急停、score-slam 比分砸落、impact-burst-kit 落点冲击套件（波及邻卡）
+适用: 主角卡/KPI 卡的重拳入场；impact-feedback 管落位后的反馈，本卡管入场本身就是冲击
+能量: 高
+时长: 单式动作段 6–22f + 冲击余波 ~16f + hold ≥45f（demo：A 120f / B 135f / C 140f）
+标签: ui-entrance
+---
+
+## 意图
+库内入场词汇的力度上限一直是 deck-deal-flyin 的"发牌"——快但不重。
+本卡补"砸"这一档，三种口味：A 是方向感——卡片带鱼眼级夸张透视贴着
+镜头甩进来，"啪"地弹平，动漫金田流的潇洒；B 是重量感——KPI 卡从
+镜头前 2.6 倍大小砸落，圆环+尘点+震屏三件套同帧起爆，体育比分弹窗
+的分量；C 是传导感——B 的三件套之上，冲击波前沿扫过左右邻卡时把
+它们可见地推开再弹回，"这一下震到了邻居"，一件事说清力量大小。
+选型按叙事需要：告诉观众"它来了"用 A，"它很重"用 B，"它震动了
+全场"用 C。
+
+## 三式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A kanada-perspective-snap | perspective 260→1800px + rotate3d 62°→0 + scale 1.8→1 甩入 18f（姿态比位移晚收），末 5f 过冲 +6° 弹簧弹平 + 集中线，长斜影收正 | 单卡潇洒亮相；调性偏动漫/轻快 |
+| B score-slam | 卡从镜头前 scale 2.6/rotate 5° 六帧 ease-in(quad) 砸落，落点帧冲击环+碎片火花+震屏+白闪同帧，比分数字晚 3/6f 二次落地 | KPI/比分类重磅数字登场 |
+| C impact-burst-kit | 主卡从镜头前砸进页面空槽 + B 三件套 + 冲击波前沿按半径-距离精算扫过邻卡帧，邻卡外推 34px + rotate ±3.5° 阻尼弹回 | 页面上已有邻居时的"全场震动" |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 甩入 | 18f：translateX −1350→0 走 EASE.snappy（急停），透视/扭转/缩放走晚收曲线 bezier(.62,0,.3,1) 16f——卡片"扭着"冲到位、最后几帧才拍平；按 x 速度给水平 SpeedBlur（0.2×速度、≤26px）+ 身后 7 条速度线 | 快于 12f 读不到鱼眼畸变，慢于 24f 泄劲；姿态与位移同曲线同时收，到位前几帧就已经平了，鱼眼感只剩第一帧 |
+| A 落定 | rotateY 15–20f 冲到 +6°，20f 起 spring(damping 16) 回 0 + 8px 震屏 2f + 48 道集中线 9f 向外退散 + 斜长影收正；卡内文字晚 3f 落定（片名 −10° skew 收正） | "啪"在过冲回弹那一下，不在位移结束；集中线超过 10f 读作特效贴纸 |
+| B 砸落 | 0–9f 悬在镜头前（2.75→2.6、虚化 10px、半透看得见背景）→ 9–15f ease-in(quad) 砸到 0.965 → spring(damping 14) 回 1 | ease-out 落地是"放下"，ease-in 才是"砸" |
+| B 三件套 | 冲击环直径 120→1500px/16f（白芯 9→1.5px + 金色柔辉）+ 14 片多边形玻璃/金箔碎片飞 280–580px（+16 道火花）+ 震屏 18px 指数衰减 5f（偏竖向）+ 2f 白闪 | 原案(720px/10px 尘/8px 震)全档不可感，实渲已 ×1.5–2；实黑粗环/黑方块尘读作"贴纸" |
+| B 解耦命门 | 环/尘的"扩散"用 out-cubic、"消散"用线性帧时间 | 同用 out-cubic 前段跑太快，刚扩开就淡没 |
+| C 波及帧 | 前沿过邻卡中心距反解（环半径 100→1100/16f，514px 距 ≈ 落点后 3f）；包络 cos(t/2)·e^(−t/8)，40f 硬钳 0；推开瞬间按速度给水平拖影 | 邻卡与主卡同帧动读作整版抖动，晚 3f 才是"被波及" |
+| C 悬停蓄力 | 0–16f 主卡悬在空槽上方：上提 20px、scale 1.55→1.6（smooth）、槽内接触影随高度变实，再 16–22f ease-in(cubic) 砸进槽 | 悬停段死停读作"卡住了"；蓄力幅度大于 30px 就成了另一个动作 |
+| 景深 | B/C 离镜头近（scale 大）时按高度给虚化（B ≤10px、C ≤7px），落地清晰 | 近镜头元素锐利反而读不出"从镜头前砸下来" |
+| 收尾 | 全部余波归零后真静止 ≥45f | 重拳 hold 按平常两倍给（同 beat-cut A 判例） |
+
+## 已知坑
+- demo 用 video-shotcraft 的宣传内容调校（A 发布片首映卡 / B「Shotcraft vs Keyframes」终场比分 / C 成片规格页 Launch film 卡）——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 亮场（C）上冲击环要配一层白色压力盘打底、环本身用饱和强调色，暗场（A/B）用白芯 + 色辉；
+  亮底上的白环 / 暗底上的黑环都几乎不可见
+- 三式都带震屏，震屏族（impact-feedback）同一镜头
+  只能有一个震源；三式互相之间同镜头也只能选一
+- 声音强依赖：A 的"啪"、B/C 的音爆必须同帧钉（sound-design §4.5），
+  无声版 B/C 的三件套读作"卡在抽搐"
+- C 式邻卡必须先驻场稳定 ≥15f 再被波及——邻卡自己还在入场时被推开，
+  因果链读不出来
+- 全片砸入 ≤2 次；三次以上每次都响等于都不响（P4）
+
+## 参考实现
+demos/effects/slam-entrance-moves/
+（ImpactBurstKit.tsx / KanadaPerspectiveSnap.tsx / ScoreSlam.tsx）

package/lib/motion/shotcraft/upstream/references/shots/effects/spotlight-sweep-moves.md

@@ -0,0 +1,52 @@
+---
+name: spotlight-sweep-moves
+一句话: 暗场聚光显影三式——A 醒睡扫过（光到即亮光走即暗）、B 贴边泛光横摇（紫光贴 UI 边缘渗入+聚光匀速右移）、C 角落匀速显影（径向聚光从角落匀速扩张点亮全屏）；黑场里"光即叙事"的 UI 展示
+适用: 暗色调品牌片里逐个介绍 UI 面板/功能区；黑场开场把界面"点亮"登场；段落间光转场
+时长: 单式 3.5–4.5s；A/B 可串联成巡礼段
+能量: 中低（克制、神秘感，爆点在"亮起"瞬间）
+标签: ui-entrance、transition
+---
+
+## 意图
+黑场里观众只能看见光给看的东西——聚光既是照明也是运镜和剪辑：
+光到哪里哪里登场，光走即谢幕。三式共用"贴边紫色辉光光线"这个
+身份元素（光线贴着 UI 边框/logo/顶边走，辉光要亮要糊，是光在
+"抚摸"界面而不是描边动画）。命门是**匀速**：聚光的移动/扩张
+严格 linear——缓动会让光有"意图"，匀速才读作探照灯的机械扫掠
+（C 式判例：linear 但半径终值过大＝前 1/4 就饱和，观感照样不匀速）。
+
+## 动效核心
+**A 醒睡扫过**（glow-wake-sleep-panel）：radial 显影罩跟随光头从左
+向右匀速移动，范围外全黑；贴顶边紫色光线三层辉光（blur26 宽糊+
+blur9 中层+亮芯+粉色偏移层）随扫光同步走，经过 logo 时 boxShadow
+描光、到右缘点亮竖直残光；尾段光走面板沉回黑暗——有醒有睡。
+**B 贴边泛光横摇**（slide-spotlight-pan）：光线锚定面板边缘（先绕
+左上角竖缘、转角后沿顶边横走），紫光晕染渗入 UI 顶部内侧（光从
+边缘渗进界面）；聚光头匀速右移显影、面板同时匀速左滑＝相机右摇感。
+**C 角落匀速显影**（corner-spotlight-reveal）：左上角径向聚光半径
+严格 linear 扩张，照到显影照不到沉黑，最终全亮（光即转场）。
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 聚光移动/扩张 | 全程 linear、零缓动 | **匀速是命门**——全程零缓动；加 ease 读作光有主观意图 |
+| C 式半径终值 | 恰好在片尾覆盖全屏（1300@1080p/100f） | 终值过大＝提前饱和假匀速：亮度采样须全程平滑爬升（实测 8/46/101/…/238） |
+| 贴边光线辉光 | 3–4 层（blur26+blur9+亮芯+粉偏移） | 层少读作细线描边；辉光要够亮够糊才是"光" |
+| 光线锚定 | 严格贴 UI 边缘/顶边/logo | 光线脱离边缘漂浮＝失去"抚摸界面"语义（A 式返工判例：定位丢失紫光跑到底边） |
+| 显影罩 | radial 渐变硬边略糊（feather ~15%） | 边太硬像圆形遮罩；太糊没有"照到/照不到"的界线 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 light-play-moves 分工：那张是元素/文字上的
+  光泽戏（sheen/辉光呼吸）；本卡光是**运镜和剪辑**（显影/谢幕/转场），
+  光决定观众看什么
+- 三式重做判例：聚光扫过必须带贴边光线同行（v1 只有显影罩被裁
+  "改改再看"——裸聚光没有身份，贴边紫光才是这个手法的签名）
+- 原片（clickup-30）光线转角有一瞬彩虹色散，demo 未做；实战可
+  在转角帧加 1–2f 色散层提质感
+
+## 参考实现
+demos/effects/spotlight-sweep-moves/
+（CornerSpotlightReveal.tsx / GlowWakeSleepPanel.tsx / SlideSpotlightPan.tsx）
+原片出处：clickup-30.mp4

package/lib/motion/shotcraft/upstream/references/shots/interaction/autolayout-gap-dial.md

@@ -0,0 +1,60 @@
+---
+name: autolayout-gap-dial
+一句话: 间距拨盘驱动布局——一排链接块带框选描边+缝隙间距标注，徽章数字逐格跳动、块被参数实时推开再弹簧回弹归位；"参数驱动布局"的可视化
+适用: 设计工具/低代码产品的"改一个数、界面跟着动"卖点镜头；"用设计工具语义做包装"的品类语言
+时长: ~5s（150f：框选入场 + 预备回收 10f + 拉松 34f + 屏息 hold 20f + 弹簧回弹 + 落定 hold）
+能量: 中（工具理性型，爽点在数字与位移的锁定同步）
+---
+
+## 意图
+"参数改了、UI 变了"是设计工具的核心承诺，但通常拍成"点面板→切
+结果"的前后对比，因果被剪掉了。本卡把因果拍成连续镜头：间距徽章
+数字逐格跳，链接块**同帧**被推开，测量线实时拉长——数字就是缰绳，
+布局就是马。框选描边+8 手柄+间距标注全是设计工具的母语，观众一眼
+认出"这是在工具里调参数"。回程故意用欠阻尼弹簧过冲（缩到比起点
+更紧再回稳），把"归位"做成一次有弹性的收尾。与 type-and-filter
+分工：那是"输入内容→列表收敛"的检索因果，本卡是"拨数值→几何
+重排"的参数因果。
+
+## 动效核心
+- **gap 一个参数管全部**：块位置由 gap 重算（整排保持居中）、测量
+  线宽=gap、徽章钉缝隙中心、顶部大读数与拨盘刻度尺——所有元素从同一数值派生，锁定同步
+  是本卡的全部说服力
+- 参数曲线：先预备回收 12→6（10f swift，"往回收再冲出去"）；去程 6→104 走 34f swift
+  （不对称 in-out：起步稍快、落点很软）；屏息 hold 20f；回程 spring(damping 9, stiffness 80,
+  mass 1.1) 故意过冲到起点以下再回稳（过冲段 ×0.45 压缩：104→约 7 再回 12，gap 永不为负）
+- 读数做主角：顶部 196px 细体 tabular 数值 + px 单位 + 760px 拨盘刻度尺（刻度随 gap 横滚过中心
+  金针）；拨动中读数由白转测量金（带 ~6f 余温），松手回稳后褪回白；数值步进 2 显示，
+  跳数 scale 脉冲 1+0.06·|sin| × 速度门限
+- 导航块按自身速度做横向运动模糊（块速度 = (i−2)·dgap/dt，外侧块拖影最长），静止为 0
+- 框选描边 spring 从外侧 26px 收拢，8 手柄 1.2f 错峰弹出，图层名旁实时显示整排尺寸；
+  间距标注 = 虚线延长线 ×2 + 测量线带端刺 + 跟随徽章，错峰升起
+- demo 美术：graphite 暗场，选择白 + 测量金两色语义（画面里只有被拨动的数是有颜色的）；
+  相机整段极缓推近 2.5%
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| gap 幅度 | 12→104px（原片 20→24，demo 按裁决加大） | 原片幅度肉眼几乎不可感——可感性判例：看不出就加大做极端版；实战至少 4–5 倍行程 |
+| 预备 | 12→6，10f swift | 先收后放给主动作蓄力；回收 >30% 读作数值抖动 |
+| 去程时长 | 34f swift | 快了读作抽搐；慢过 60f 数字跳动和位移的绑定感松掉 |
+| 屏息 hold | 20f | 让观众读清"最松"的那一帧；<12f 读不到峰值 |
+| 回程弹簧 | damping 9 → 过冲到起点以下再回稳（过冲段 ×0.45，最紧约 7px） | 过冲是"松手回弹"的手感来源；damping ≥13 直落可惜 |
+| 数字步进 | 步进 2 + 跳数 scale 脉冲 0.06 × 速度门限 | 逐 1 跳太碎读作毫秒表；步进是"拨盘咔哒"的颗粒感 |
+| 运动模糊 | 横向 stdDeviation = min(9, |块速度|×0.5) | 只在拨动段出现；全程常驻会让块字读不清 |
+| 标注几何 | 延长线 58px、测量线钉块底 +74px、徽章钉缝隙中心 | 标注必须随 gap 实时重算——任何一处滞后即穿帮 |
+| 块宽 | 不等宽（252/206/278/268/220，高 120） | 等宽读作示意图；不等宽才像真导航 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 数字与位移必须同源同帧：徽章显示值和块坐标都从同一个 gap 派生，分开动画哪怕差 1f，"参数驱动"的信任即碎
+- demo 顶部大读数 + 拨盘刻度尺与布局同源同帧，实战里若画面已有真实工具面板（检查器数值框）就删掉大读数，别双重报数
+- 同族扩展：gap 只是一维，radius/padding/rotation 同语法可换参数——但一镜只拨一个参数，两个以上读作乱调
+- 框选描边+手柄是"设计工具语义"借用（figma/framer 母语），非设计工具受众的片子慎用，读不懂框选就只剩块在挪
+- 声音：徽章每跳一格一声极轻 tick（拨盘咔哒），回弹落定一声 pop；tick 密度跟步进走
+
+## 参考实现
+demos/interaction/autolayout-gap-dial/
+（AutolayoutGapDial.tsx）
+原片出处：framer-ai 4.5–5.5s

package/lib/motion/shotcraft/upstream/references/shots/interaction/canvas-materialize-moves.md

@@ -0,0 +1,57 @@
+---
+name: canvas-materialize-moves
+一句话: 内容"物化上画布"两式——panel-to-canvas 行倒卡（面板表格行沿弧线飞出、跨容器变形成画布卡片）与 diagram-cascade 级联生成树（prompt 打字后节点逐层弹出、连线先于节点生长）
+适用: AI/协作工具"生成结果落到画布上"的叙事段落；A 式讲"已有内容换了个存在形态"，B 式讲"从一句话长出一棵结构"
+时长: A ~5s（150f）/ B ~6s（180f）
+能量: 中
+标签: ui-entrance
+---
+
+## 意图
+库内生成叙事只有"窗口内逐字写出"（document-typewriter-reveal 文档自己写出来）
+和"图表自己活起来"（chart-live-moves），没有词管**内容离开容器、在
+开放画布上物化成新实体**。本卡补这一块：画布是舞台，生成物是登台的
+演员。A 式的命门是跨容器形态迁移——同一条内容从"行"变成"卡"，位置
+/宽高/圆角/内容布局在一条 spring 上同步插值，观众读到"是它飞过去
+变的"而不是"删一个加一个"；B 式的命门是级联时序——线牵出节点、层
+喂出层，结构感来自先后而非同时。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A panel-to-canvas 行倒卡 | 光标逐个点复选框打勾→按钮按下→三行先拔起再沿上抛弧线错峰飞出，途中行形态与卡形态交叉淡化，落位带倾角与落地压扁；面板行槽塌陷成虚线留白 | 批量导入/一键上板：内容从列表态迁移为空间态 |
+| B diagram-cascade 级联生成树 | prompt 逐字敲出（敲完描边确认、提交后描边流光=生成中）→prompt 底部滴线接根（渐变描边主角）→2 子→4 孙逐层从顶端口拉出，折角连线带彗星头先行 10f，相机从 prompt 特写拉远揭示全树，成树后整棵呼吸一拍 | AI 生成结构图/脑图/ER 图：一句话长出一棵树 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 打勾 | 14/24/34f 逐个（光标 swift 弧线逐个点中），spring(damping 11, stiffness 300) pop + 勾线 7f 描出 | 打勾是"预告"，全删观众不知道要飞谁；同帧齐勾读作静态已选 |
+| A 起飞错峰 | 按钮 52f 按下，三行 56/62/68f 拔起（4f：放大 2% + 阴影加深）后起飞（错峰 6f） | 同帧齐飞读作复制粘贴；错峰 >12f 尾行像掉队；不拔起直接飞读作被删除 |
+| A 飞行插值 | spring(damping 17, stiffness 95, mass 0.9)；位置走二次贝塞尔，中点上抬 220px；宽高晚 3f 收敛 | 直线飞读作平移不读作"倒出来"；中点抬 <100px 弧线感消失；尺寸与位置同步则少了"父先子后"的重量 |
+| A 形态迁移 | 行 626×104 → 卡 486×300，圆角 18→24，rowOp 在 us 0.08→0.4 灭、cardOp 在 0.5→0.8 亮 | 两套内容交叉淡化必须错开——中段两态同显即穿帮 |
+| A 落位倾角 | −2.5 / 1.8 / −1.2°，落地 6f scaleY 0.97 压扁回弹 | 全正读作网格排版；>4° 读作散落故障 |
+| A 速度模糊 | SpeedBlur amount 0.32、max 14（按弧线速度方向） | 只在飞行段；落定后归零 |
+| B 打字 | 每字 0.95–1.2f 不均匀、空格停 1.7f；敲完 prompt 条描边转紫确认，+4f 按下提交键 | 匀速打字读作机器；无确认态则"敲完"与"开始生成"之间没有因果扣 |
+| B 相机 | 开场 1.3× 推近 prompt 居中；提交后 72f smooth 拉远到 1.0 | 不推近则前 2s 画面下半空着；拉远要与级联同时进行，树长在镜头"退"出来的空间里 |
+| B 级联时序 | 根 = 提交 +14f，层间隔 22f、同层兄弟错峰 5f；节点 spring(damping 14, stiffness 190)，缩放原点 = 顶边中点（从端口拉出） | 层间隔 <12f 读作一次性全出；兄弟同帧读作复制；中心缩放读作弹窗 |
+| B 连线先行 | SVG 圆弧折角 path（父底端口→中线→子顶端口）描线 16f ease-out，比子节点早 10f；线头一颗彗星光点 | "线牵出节点"是因果感来源；线晚于节点就成了补笔 |
+| B 收尾呼吸 | 末节点 +22f 起，以树心为原点 scale 1→1.03→1（smooth，28f），背后极光同步亮一档 | 呼吸是"成树"的句号；>1.06 读作缩放故障 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 chart-live-moves 分工：那卡是数据图表自身的活性（流线/点阵/爆轴），
+  B 式是结构图的**诞生过程**——图活着≠图正在被生成，别拿 B 式去演已有图表
+- A 式行槽必须塌陷成虚线留白——行飞走后原位完好如初，"迁移"就退化成
+  "复制"，语义全失
+- A 式交叉淡化窗口（rowOp 灭于 u≈0.45 前、cardOp 亮于其后）是防穿帮的
+  命门；spring 有过冲，u 可能短暂 >1，内容 opacity 都要 clamp
+- B 式呼吸原点必须是树的视觉重心（demo 960,620）而非画面中心，
+  不然读作整屏 zoom
+- B 式彗星头靠路径弧长取点：折角用 SVG 圆弧（A 命令）而非二次贝塞尔，长度才能解析算准，
+  线头与描线端点不脱节
+
+## 参考实现
+demos/interaction/canvas-materialize-moves/
+（DiagramCascadeBuild.tsx / PanelToCanvasMaterialize.tsx）
+原片出处：miro-promo 84–92s（A 式）/ 104–116s（B 式）

package/lib/motion/shotcraft/upstream/references/shots/interaction/chip-grid-single-select-blackout.md

@@ -0,0 +1,51 @@
+---
+name: chip-grid-single-select-blackout
+一句话: 五个选项 chip 以 3+2 居中排布逐个淡入；选中帧先插一帧灰色按压块，紧接数帧内底色变墨黑、文字变白并做 1→1.04→1 极轻回弹，其余 chip 淡到 18% 但位置锁死；随后余项归零，黑 chip 上移收窄，下方升起结算价格
+适用: 单选/套餐/档位选择的交互演示；"选了它之后会怎样"的因果镜头；价格/参数结算类链路
+时长: 约5.5s（165f@30fps）
+能量: 中低（唯一的爆点是那一帧灰闪，其余都在收）
+---
+
+## 意图
+一帧灰闪 + 三帧反黑，是把真实 UI 的 `:active → :selected` 两级状态
+拆开演。观众看到的是"手指按下"再"系统确认"，而不是一次渐变。其余
+chip 降到 18% 而**位置绝不移动**：一旦重排，观众会以为页面刷新了，
+"单选"的语义就丢了。
+
+## 动效核心
+- 5 个 chip 分 3+2 两行居中（1080p 原生：高 96、圆角 48、gap 22、36px 字，固定宽 346/364/476/236/330），
+  8f 起按 3f 间隔 snappy 升起；上方眉题 + 84px 问句先到
+- 光标 26–54f 从右下走 swift 弧线移到目标 chip（因果预告），56f 按下
+- **1 帧按压灰闪**：仅 FS=56 这一帧，`rgba(120,128,146,.5)` 覆盖层
+- **反黑**：57→62f linear（5 帧）驱动背景 白→墨黑 `#0b1020`、描边、文字 墨→白，同时 ✓ 从 0 宽长出
+- **按压回弹**：`sc = 1 + sin(pr·π)*0.04`，pr 走 57→66f——正弦保证起止都精确回到 1
+- **余项降级**：57→66f outQuad 把 opacity 压到 18%，`transform` 恒为 `none`
+- 主角光：反黑后 chip 底下亮一圈极淡钴蓝落地光（只给主角一次），阴影随抬升变深变大
+- **收束**：101f 起（选中后≈1.5s）余项 9f 归零；黑 chip 18f smooth 上移到 y=330、scale→0.88、
+  横向回中线（几何由固定宽算出，不运行时测量）；问句同时上移淡出让位
+- 结算：108f 原价 $42.00 升起 → 118f 一道划线划掉并退灰 → 116f 起现价 $34.44 逐字升起（180px）
+  → 128f 钴蓝「Save 18% · billed $413.28 yearly」overshoot 弹出；134–165f hold
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 入场 | 8f 起、间隔 3f、各 16f snappy | 5 个 chip 在 1s 内铺完，把时间留给选中段 |
+| 选中时刻 | FS = 56f（约全片 1/3） | 前段读题、后段看结果；早于 40f 观众还没读完选项 |
+| 灰闪 | 1 帧，rgba(120,128,146,.5) | **就一帧**：给 2 帧以上就读作 hover 高亮，不是按下 |
+| 反黑 | 57→62f linear（5f） | linear 是故意的：加 ease 会让"变黑"这件事有过程感，太软 |
+| 按压回弹 | 1 + sin(pr·π)·0.04，跨 9f | 0.04 是极轻；到 0.1 就成了弹跳按钮，抢戏 |
+| 余项降级 | 降到 18%，位置 transform:none | **位置锁死是命门**：降到 18% 仍在原位，才读作"没被选中"而非"消失了" |
+| 收束时刻 | 101f（选中后≈1.5s）起，18f smooth in-out | 1.5s 是让观众看清选中态的最短驻留；缩到 0.5s 就赶 |
+| 上移收窄 | 到 y=330、scale→0.88，横向补回中线 | 不补中线的话上移后会偏在左边，读作"被拖走"；缩过 0.85 字低于 32px |
+| 结算顺序 | 原价 → 划线 → 现价 → 省额胶囊，间隔 8–10f | 先给旧价再划掉，观众才读得到"变便宜了"的因果 |
+
+## 已知坑
+- 选中 chip 的回中线位移由固定 chip 宽算出（不运行时测量 offsetWidth）——改文案时要同步改宽度表，
+  否则字溢出或上移后偏离中线
+- 其余 chip 的 `transform` 必须显式写 `'none'`，不能靠 flex 自动重排，否则余项归零时会横向滑动
+- 占位内容：5 条计费周期选项名（Annual billing … Nonprofit rate）+ 结算「$42.00 → $34.44/mo、Save 18%」，
+  落地全部替换；选项名过长会撑破固定宽（第三条 "Two-year commitment" 是长名压力测试）
+
+## 参考实现
+demos/interaction/chip-grid-single-select-blackout/
+（ChipGridSingleSelectBlackout.tsx）

package/lib/motion/shotcraft/upstream/references/shots/interaction/collab-cursor-moves.md

@@ -0,0 +1,41 @@
+---
+name: collab-cursor-moves
+一句话: 协作光标当演员——cast-ensemble 五光标群演氛围层（错峰飞入+正弦漂移+打字 cameo+聚拢围观）
+适用: 协作/多人主题的画布场景，给画面铺"团队在场"体温
+时长: A ~5.2s（156f）
+能量: A 低中（氛围层，可垫任何时长）
+---
+
+## 意图
+库内光标一直是"操作工具"（cursor-flyover 的光标
+是单光标点击导览）。本卡把带身份名牌的协作光标升格成**演员**：
+五枚光标错峰入场后持续漂移当氛围粒子，"团队在场"感全靠它，其中一枚
+还能停下来打字（cameo 戏份）。SVG 光标+名牌 chip 成本极低、叙事密度
+极高，是"协作"主题最便宜的视觉论证。
+
+## 式
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A cast-ensemble | 5 枚具名彩色光标错峰 spring 飞入 video-shotcraft 的分镜白板（头像组同帧弹出、便签带作者色）→双频正弦漂移驻场→一枚挂在插入点上打出简报卡标题→结尾全员 smooth 聚拢围观 | 画布/白板类产品全片氛围层；主内容之外需要"别人也在"的背景活性 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 入场 | 5 枚 delay 2/7/11/16/22f 错峰，spring(damping 15, stiffness 80)；名牌晚 10f 淡入+上浮 12px；右上头像组同帧弹出（槽宽随弹出长） | 名牌跟光标同帧出现读作贴纸；随减速淡入才是"人到了自报家门" |
+| A 漂移 | 双频正弦叠加（0.055/0.021 rad/f，每枚相位不同），幅度 ±40/26px | 单频正弦读作钟摆；双频不同相才是"人手的随机" |
+| A 打字 cameo | 48–104f 打 29 字（1.6–2.4f/字确定性抖动，空格后多停 0.9f）；光标箭头挂在行内插入点锚点上，换行也跟着走；打字时手稳（漂移压到 0） | 箭头和插入点分开算位置必错位；行内零宽锚点让浏览器排版替你算 |
+| A 聚拢 | 98f 起 28f smooth 到卡片四周围观位（不压标题和眉题），漂移幅度衰减到 25% 保留 | 聚拢后漂移不能归零——完全静止的光标群读作死机 |
+
+## 已知坑
+- demo 在手搓画面上调校通过（瓷白白板 + 便签 + 简报卡，板名挂 video-shotcraft 标志，标题 "Ship a launch film by Friday."）——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 名牌颜色=身份编码，全片必须一致（蓝=Designer 就一直蓝）；中途换色观众会以为换了人
+- 换标题文案时保持字数与空格数，打字节奏（每字抖动按下标取、空格多停）与收尾帧才不变
+- 漂移光标永远不许盖住正在阅读的主内容——氛围层要让戏，漂移范围避开主体安全区
+- 与 cursor-flyover 分工：那是光标"操作 UI"（点击有 payload），本卡光标"表演给你看"（位移即剧情）；光标要点东西时回那张卡
+- 声音：入场每枚一声极轻 pop，漂移段静，打字段 keyboard 轻声
+
+## 参考实现
+demos/interaction/collab-cursor-moves/
+（CursorCastEnsemble.tsx）
+原片出处：figma-devmode 0:05 + miro-promo 全片 + pitch-app 82–90s 打字 cameo

package/lib/motion/shotcraft/upstream/references/shots/interaction/glass-pill-dictation-typing.md

@@ -0,0 +1,53 @@
+---
+name: glass-pill-dictation-typing
+一句话: 一条定宽玻璃胶囊以约 1.25 倍略大弹出后缓落到位，内部自左淡到右浓铺一层强调色暖光；光标先行、随后匀速打出听写句，光（连同胶囊背后的环境光）随打字进度渐渐退去，收尾成一条中性的磨砂玻璃条
+适用: 语音/AI 输入框的登场；"跟它说话"的交互提示镜头；高能段之间的一个安静过渡拍
+时长: 约3.3s（100f@30fps）
+能量: 低（全片最安静的一拍，只有光在退）
+---
+
+## 意图
+用"光随输入熄灭"讲一件很小的事：待命时它在发光（等你说话），你一开口
+它就把光让给文字。3.3s 里只做三件事——弹出、打字、光退。任何额外动作
+（弹跳、色变、图标动画）都会让这一拍不再是休止符。
+
+## 动效核心
+- 胶囊 1240×132、圆角 66、`padding: 0 20px 0 58px`，**定宽**（不随打字伸缩）；
+  听写字 56px、右端 92px 圆形声波按钮
+- 出场 `scale 1.25→1`，snappy（强 ease-out）20f；opacity 前 2f 就满——先"在了"再落位；
+  落位前 14f 带 6px→0 的景深虚化（放大段读作"离镜头更近"）
+- 材质：`backdrop-filter: blur(26px) saturate(1.3)` 真磨砂（背后的暖色光斑被它晕开），
+  上亮下暗白色体积渐变 + 1.5px 白描边 + 顶沿两端渐隐高光线 + 底缘内暗边 + 暖色两层落地影
+- 内嵌强调色光：`linear-gradient(90deg, α0 → α.18 @38% → α.62 @78% → 杏色 α.95 @100%)` 左淡右浓，
+  外加右下角一团 screen 叠加的高光——光在胶囊**内部**
+- 打字：光标 f2 先行，字符 f8 起匀速 2f/字铺完 28 字；光标 f66–74 撤掉
+- 光熄灭 `g = 1 − smooth(f10→f72)`，与打字同窗口；`g` 同时驱动四处：胶囊内渐层、胶囊背后那轮暖色"太阳"、
+  胶囊下方地面反光、声波按钮（实心暖色 → 描边中性），外泛光 `60g px`
+- 声波 5 根竖条基准高 `[30,16,24,13,20]`（左高右低），叠 `±2.4·sin(f·0.5 + i·1.7)` 极轻呼吸
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 胶囊定宽 | 1240px（≈整句宽度 1.8 倍） | **定宽是关键**：随字伸缩会读作 chip 而不是输入条 |
+| 出场缩放 | scale 1.25→1，snappy 20f | 1.25 倍是"从观众面前落回去"的量；1.5 倍就成了 pop 弹窗 |
+| opacity 时序 | 前 2f 跳满（早于缩放落位） | 同步淡入会让它像"渐渐出现"，失掉那一下轻微的实感 |
+| 内嵌光 | 90deg、0 → .18@38% → .62@78% → .95@100% | 光必须在胶囊内部；改成外 glow 就成了"待通知"而不是"待输入" |
+| 打字 | 28 字符，f8 起 2f/字匀速 | 加 ease 就读作"有人在犹豫"；听写是匀速的 |
+| 光熄灭 | 1 → 0，f10→f72 smooth | 与打字同窗口是全片唯一的因果：光让位给文字 |
+| 环境光跟随 | 背后暖光 0.15+0.6g、地面反光 0.22g | 只熄胶囊、环境不变，亮场里"光退"会读不出来 |
+| 声波竖条 | 5 根、±2.4px | 幅度到 6px 就成了"正在录音"的活跃态，与"待命"矛盾 |
+| 光标 | f2 先行、f66–74 撤 | 光标先于文字出现，是"输入框已就绪"的信号 |
+
+## 已知坑
+- backdrop-filter 只晕它**背后**的层：暖色光斑必须放在胶囊之下（同一层叠上下文里先画），
+  光斑离胶囊太远时磨砂看起来就是一块平白板
+- 亮场里光的明暗对比远小于暗场：内嵌光要给到杏色 .95 的饱和度，并让背后环境光一起退，否则"光退"不成立；
+  要做暗场版，把舞台换回近黑、光色降饱和即可，曲线不用动
+- 声波竖条是持续呼吸（不受 g 控制），首尾帧高度不同——用作 loop 素材时把频率调成 2π/时长 的整数倍
+- 打字进度 `floor(p·len + 1e-6)`，那个 epsilon 是防止末字符在整点因浮点误差不出现，别删
+- WARM / APRICOT 两个变量是内嵌光、外泛光、环境光、按钮共用的品牌色，换项目只改这两个
+- 句子长度变了要同步调胶囊定宽（保持 ≈ 句宽 1.8–2 倍）与打字窗口
+
+## 参考实现
+demos/interaction/glass-pill-dictation-typing/
+（GlassPillDictationTyping.tsx）