hyper-animator-codex 0.7.1 → 0.8.0

package/skills/hyper-animator-codex/references/hyperframes-intent-workflow.md

@@ -12,16 +12,24 @@
 1. 接收自然语言需求。
 2. 抽取初始 `intent_profile`：用途、平台、画幅、内容类型、风格、动效、时长、是否需要字幕/转场/片尾。
 3. 若用途或画幅缺失，调用 `AskUserQuestion` 第一轮澄清。
-4. 用 `hyperframes-catalog-map.json` 对 catalog items 打分。
-5. 选出候选 plan：主场景 Block、可选 Component、可选 Transition、可选 Outro。
+4. 用 `hyperframes-catalog-map.json` 对可渲染 catalog items 打分；同时运行
+   `scripts/query_shotcraft.mjs`，从 `references/shotcraft/catalog.json`
+   检索镜头语法、节奏、转场和运镜参考。
+5. 选出 dual-catalog 候选 plan：主场景 Block、可选 Component、可选
+   Transition、可选 Outro，以及每个镜头的 ShotCraft 参考。
 6. 判断 generation mode：组装现有 catalog，还是生成新 HTML。
 7. 调用 `AskUserQuestion` 第二轮澄清样式、动效、候选取舍，以及 generation mode。
 8. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
-9. 若选择 `generate_new_hyperframes_html`，按 patterns 文档生成完整 block/component HTML。
-10. 运行 pre-render quality gates。
-11. 展示方案摘要和 HTML preview，让用户验证/确认。
-12. 根据反馈修订。
-13. 渲染视频。
+9. 若选择 `generate_new_hyperframes_html`，按
+   `references/HyperFrames-AI-Generation-Patterns-codex.md` 生成完整
+   block/component HTML；ShotCraft TSX 只作为动效参考，不引入 Remotion
+   运行时。
+10. 按 `contracts/shot-plan.schema.json` 写出镜头计划，并运行
+    `scripts/validate_shot_plan.mjs shot-plan.json`。
+11. 运行 pre-render quality gates。
+12. 展示方案摘要和 HTML preview，让用户验证/确认。
+13. 根据反馈修订。
+14. 渲染视频。
 
 ## Intent Profile
 
@@ -166,6 +174,14 @@ score =
 - 字体、图片、GLTF、WebGL 等 async 资源 ready 后再注册 timeline。
 - WebGL/Three/shader 必须有 fallback timeline。
 
+## Model Routing
+
+- `gpt-5.6-sol` 仅用于页面生成和动画编写。
+- 需求抽取、文件检测、catalog 查询、镜头计划、音频提示词、校验和打包
+  使用 `gpt-5.6-terra` 或同级快速经济模型。
+- 不为模型路由自动新增 Agent 或其他实体；在运行环境支持模型选择时才
+  应用路由。
+
 ## Pre-Render Quality Gates
 
 渲染前必须检查：

package/skills/hyper-animator-codex/references/minimax-music-workflow.md

@@ -6,9 +6,20 @@ Use this when the user wants generated background music or asks whether Hyper An
 
 Do not hand-assemble MiniMax HTTP requests in agent reasoning or shell commands. Always call `scripts/generate_minimax_music.mjs`. The script owns request validation, retry policy, error normalization, audio writing, metadata writing, and secret redaction.
 
-## MiniMax Preference
+## Required Provider
 
-Prefer MiniMax before other background-music sources when `config/minimax.json` exists in the installed skill or `MINIMAX_API_KEY` and `MINIMAX_GROUP_ID` are present in the environment.
+Generated BGM uses MiniMax mainland China (`minimax_cn`) only. Never invoke
+HeyGen, Kokoro, MusicGen, or a generic HyperFrames audio fallback. Never
+install a fallback model/runtime.
+
+Before generation, validate the provider and endpoint:
+
+```bash
+node scripts/validate_provider_policy.mjs \
+  --kind bgm \
+  --provider minimax_cn \
+  --endpoint https://api.minimaxi.com/v1/music_generation
+```
 
 The installed config shape is:
 
@@ -22,6 +33,11 @@ The installed config shape is:
 
 Do not print or echo the raw API key. `group_id` is stored because the installer collects it, but the current `/v1/music_generation` API call uses only `Authorization: Bearer <API_key>` and the documented JSON request body.
 
+The wrapper accepts `music-3.0`, `music-2.6`, and `music-2.6-free`. The stable
+installer default remains `music-2.6` for backward compatibility; choose
+`music-3.0` explicitly when the account has access and the user wants the
+current model.
+
 ## Clarify Music
 
 Ask only for missing choices:
@@ -83,6 +99,10 @@ Use the resulting beat map exactly as described in `references/beat-sync-workflo
 
 ## Fallbacks
 
-If MiniMax config is missing, ask whether the user wants to provide a local audio file or continue without background music.
+If MiniMax config is missing, ask whether to retry after configuration, use a
+user-provided local audio file, or continue without background music.
 
-If MiniMax generation fails, summarize the provider, model, redacted config source, and error message. Then ask whether to retry with a different prompt/model, use a local audio file, or continue without background music.
+If MiniMax generation fails, summarize the provider, mainland endpoint, model,
+redacted config source, and error message. Then ask whether to retry with a
+different prompt/model, use a local audio file, or continue without background
+music. Do not silently substitute or install another generator.

package/skills/hyper-animator-codex/references/narration-audio-workflow.md

@@ -21,6 +21,27 @@ Rules:
 
 Codex writes or edits outline/narration content. Scripts only validate, convert, call MiniMax, and write artifacts.
 
+## Provider Boundary
+
+Generated narration and BGM use MiniMax mainland China (`minimax_cn`) only.
+Never run `hyperframes auth login` or `hyperframes tts`; never invoke HeyGen,
+Kokoro, or MusicGen; and never install a fallback runtime/model. Kokoro is a
+local open-weight TTS engine, but it is outside this product contract and is
+not needed.
+
+Before a generated-audio call, validate the route:
+
+```bash
+node scripts/validate_provider_policy.mjs \
+  --kind narration \
+  --provider minimax_cn \
+  --endpoint https://api.minimaxi.com/v1/t2a_v2
+```
+
+If MiniMax configuration is missing or a call fails, stop the audio stage and
+ask the user to choose retry MiniMax CN, provide a local file, or skip that
+track. Do not choose another provider implicitly.
+
 ## Narration JSON
 
 Use this shape:
@@ -53,7 +74,7 @@ Do not hand-write MiniMax TTS HTTP calls. Use:
 node scripts/generate_minimax_tts.mjs --list-voices --voice-type all
 ```
 
-Prefer cloned voices, then generated voices, then system voices. Recommend three candidates by content tone and ask the user to choose. If listing fails, continue with `XiaoR_001` after telling the user.
+Prefer cloned voices, then generated voices, then system voices. Recommend three candidates by content tone and ask the user to choose. If listing fails, use the same explicit MiniMax failure choices; do not switch providers.
 
 Emotion labels:
 
@@ -66,10 +87,16 @@ Generate narration audio:
 ```bash
 node scripts/generate_minimax_tts.mjs \
   --narration-json narration.json \
+  --split-scenes \
   --output-dir hyper-animator-output/voice
 ```
 
 Use `--dry-run` before a real call when checking request shape or credentials.
+For multi-scene narration, `--split-scenes` is required. It writes one audio
+file per scene plus `narration-manifest.json`. Use the returned
+`duration_ms`, `start_seconds`, and `end_seconds` as the source of truth for
+shot timing. Revise the script before regenerating if actual audio duration
+does not fit the target; do not guess by stretching the visual timeline.
 
 ## Subtitles
 
@@ -78,6 +105,7 @@ Generate subtitles only when narration is used and the user wants subtitles:
 ```bash
 node scripts/generate_subtitles.mjs \
   --narration narration.json \
+  --timing-manifest hyper-animator-output/voice/narration-manifest.json \
   --output-dir hyper-animator-output/subtitles \
   --style clean
 ```
@@ -88,6 +116,8 @@ Subtitle rules:
 - no trailing punctuation;
 - one visible cue at a time;
 - JSON and SRT outputs include timecodes.
+- when a timing manifest is present, scene boundaries come from actual MiniMax
+  audio duration rather than `duration_estimate`.
 
 ## BGM, Beat, And Schedule
 

package/skills/hyper-animator-codex/references/shotcraft/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Wei Yihao
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/hyper-animator-codex/references/shotcraft/cards/ai-stream-response/README.md

@@ -0,0 +1,46 @@
+---
+name: ai-stream-response
+一句话: AI 响应面板先落一句可读摘要，再让带状态图标的证据行逐条汇入，最后统一收束成完成态
+适用: AI 助手/agent/search/copilot 的结果生成镜头；强调“结论先到、证据随后、任务完成”
+时长: 约 4–5s（120–150f，含 ≥15f 完成态静止）
+能量: 中高（信息持续增加，但阅读优先于速度炫技）
+---
+
+## 意图
+把“AI 正在工作”拍成可读的因果链，而不是日志刷屏：观众先看懂答案摘要，
+再看到证据/子任务逐条补齐，最后由完成态确认这轮工作结束。
+
+## 动效核心
+- 用目标产品真实响应面板截图做 backplate；动态区截图前隐藏，按 layout 坐标重叠回真实槽位（Q1/Q9）
+- 面板进入后摘要句先以短 wipe/淡入落定，落定后至少 12f 才起首条证据
+- 6–8 条证据行自下方 14–24px + 轻微 blur 逐行汇入；间隔逐渐收紧但保留可数节拍
+- 行体先停，状态图标晚 2–4f 由 pending 转 running/done，形成主次拖拽层级
+  （模式已沉为 assets/lib/helpers/motion.ts lagged）
+- 末条完成后只做一次面板级完成脉冲，随后全画面静止 ≥15f；不逐行 glint
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 摘要 | cue 18，10–14f reveal；摘要落定后 hold ≥12f，首行 cue ≥42 | 摘要与首行粘连会失去“结论先到”的叙事；正常速度必须能先读到一句完整结论 |
+| 行节拍 | `cue[i]=42+[0,11,21,30,38,45,51,56][i]`，每行 10–14f | 间隔 11→5f 逐渐收紧，表达工作加速；不要密到所有行同时糊成一团（R2） |
+| 行入场 | y 18px→0，blur 6px→0，opacity 0→1，bezier(0.2,0.75,0.25,1) | 位移须过正常速度肉眼阈值；大幅横飞会像通知列表，不像证据归档 |
+| 状态图标 | 比行体 cue 晚 3f；pending 环 → running 缺口环 → done 实心勾，6–8f | 图标是状态回执，不抢行文本；同帧切换全部图标会读作假 loading |
+| 完成收束 | 末图标 done 后 6f，面板边框/摘要底色 opacity 0.25→0.55→0.25 共 10f | 只做面板级一次，不逐行发光（Q4）；完成脉冲后留 ≥15f 真静止（R1） |
+| 相机 | 信息密集默认正视，zoom 1.04→1.0 微退；暗场斜拍仅作情绪变体 | Linear 参考片的斜拍不是通用命令；文字读不清时立即回正视（Q6） |
+
+## 声音
+摘要落定配一发 `transition-soft`；前 3–4 行用短 `pop` 轻声递减
+0.32→0.20，后半加速密集段合并成一条低音量 `whoosh-fast`，避免逐行机枪感；
+最终完成态用 `click-camera` 的轻量版本（约 vol 0.3）。声音在画面锁定后钉帧。
+
+## 已知坑
+- 逐字符流式打字会把视线困在字符层；宣传片时长里优先按“语义块”揭示摘要，
+  真正展示输入操作时另用 `type-and-filter`
+- 行体和状态图标若同帧落定，会像静态列表整体切换；保留 2–4f 拖拽层级
+- 行终点必须是截图里真实列表槽位，不在面板上方悬浮；动态内容也必须用虚构数据
+- 此卡借鉴 Linear Agent 发布片 t≈13–17s（进化轮 #3 breakdown #6），非用户判例；
+  参数未经本库实战项目验证，首次使用必须按 P1 在正常速度下看片，不以逐帧 diff 代替体感
+
+## 参考实现
+demos/ai-stream-response/
+（StreamResponse.tsx）

package/skills/hyper-animator-codex/references/shotcraft/cards/autolayout-gap-dial/README.md

@@ -0,0 +1,53 @@
+---
+name: autolayout-gap-dial
+一句话: 间距拨盘驱动布局——一排链接块带框选描边+缝隙间距标注，徽章数字逐格跳动、块被参数实时推开再弹簧回弹归位；"参数驱动布局"的可视化
+适用: 设计工具/低代码产品的"改一个数、界面跟着动"卖点镜头；"用设计工具语义做包装"的品类语言
+时长: ~4s（120f：框选入场 + 拉松 38f + hold + 弹簧回弹）
+能量: 中（工具理性型，爽点在数字与位移的锁定同步）
+---
+
+## 意图
+"参数改了、UI 变了"是设计工具的核心承诺，但通常拍成"点面板→切
+结果"的前后对比，因果被剪掉了。本卡把因果拍成连续镜头：间距徽章
+数字逐格跳，链接块**同帧**被推开，测量线实时拉长——数字就是缰绳，
+布局就是马。框选描边+8 手柄+间距标注全是设计工具的母语，观众一眼
+认出"这是在工具里调参数"。回程故意用欠阻尼弹簧过冲（缩到比起点
+更紧再回稳），把"归位"做成一次有弹性的收尾。与 type-and-filter
+分工：那是"输入内容→列表收敛"的检索因果，本卡是"拨数值→几何
+重排"的参数因果。
+
+## 动效核心
+- **gap 一个参数管全部**：块位置由 gap 重算（整排保持居中）、测量
+  线宽=gap、徽章钉缝隙中心——所有元素从同一数值派生，锁定同步
+  是本卡的全部说服力
+- 参数曲线：去程 12→110 走 38f Easing.inOut(cubic)；hold 14f；
+  回程 spring(damping 9, stiffness 80, mass 1.1) 故意过冲到起点
+  以下再回稳
+- 徽章数字步进 2 显示（Math.round(gap/2)*2），跳数时 scale 脉冲
+  1+0.10·|sin|；顶部大 GAP 读数块同步
+- 框选描边 spring 入场，8 手柄（四角+四边中点）；间距标注 = 竖直
+  延长线 ×2 + 水平测量线 + 跟随徽章，8–16f 淡入
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| gap 幅度 | 12→110px（原片 20→24，demo 按裁决加大） | 原片幅度肉眼几乎不可感——可感性判例：看不出就加大做极端版；实战至少 4–5 倍行程 |
+| 去程时长 | 38f inOut cubic | 快了读作抽搐；慢过 60f 数字跳动和位移的绑定感松掉 |
+| 回程弹簧 | damping 9 → 过冲到起点以下再回稳 | 过冲是"松手回弹"的手感来源；damping ≥13 直落可惜 |
+| 数字步进 | 步进 2 + 跳数 scale 脉冲 0.10 | 逐 1 跳太碎读作毫秒表；步进是"拨盘咔哒"的颗粒感 |
+| 标注几何 | 延长线 62px、测量线钉块底 +56px、徽章钉缝隙中心 | 标注必须随 gap 实时重算——任何一处滞后即穿帮 |
+| 块宽 | 不等宽（230/190/265/210/245） | 等宽读作示意图；不等宽才像真导航 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 数字与位移必须同源同帧：徽章显示值和块坐标都从同一个 gap 派生，分开动画哪怕差 1f，"参数驱动"的信任即碎
+- demo 顶部大 GAP 读数块是灰阶示意的讲解字幕，实战里若画面已有真实工具面板就删掉，别双重报数
+- 同族扩展：gap 只是一维，radius/padding/rotation 同语法可换参数——但一镜只拨一个参数，两个以上读作乱调
+- 框选描边+手柄是"设计工具语义"借用（figma/framer 母语），非设计工具受众的片子慎用，读不懂框选就只剩块在挪
+- 声音：徽章每跳一格一声极轻 tick（拨盘咔哒），回弹落定一声 pop；tick 密度跟步进走
+
+## 参考实现
+demos/autolayout-gap-dial/
+（AutolayoutGapDial.tsx）
+原片出处：framer-ai 4.5–5.5s

package/skills/hyper-animator-codex/references/shotcraft/cards/beat-cut-moves/README.md

@@ -0,0 +1,54 @@
+---
+name: beat-cut-moves
+一句话: 硬切当节拍乐器的两式——递进硬切串（间隔减半加速逼近）与连闪定格（三次白闪各切一个裁切）
+适用: 高光/冲刺段落把"切"本身打成鼓点；A 式预告片式加速逼近，B 式颁奖连拍仪式感
+时长: A 全程 ~4.3s（建立 49f + 五连切 + 定格 hold 35f）；B 全程 ~4.3s（活素材 30f + 三闪 + hold 60f）
+能量: 高
+---
+
+## 意图
+库内节奏词汇一直只管"一条运动内"的速率（speed-ramp 是同一条 take
+里变速）和"落定后停多久"（R 系呼吸判例），没有词管**多镜之间切点
+怎么排**。本卡补这一块：硬切不做任何过渡，切点间隔本身就是乐谱——
+间隔递减读作加速逼近（A），等距三闪读作快门连拍（B）。与 R 系不
+冲突：R 管落定后的停，本卡管切点排布，切串结束必须接足量 hold 把
+呼吸还回去。注意这是刻意的例外——节奏偏好判例是单向"放慢"，硬切
+串切得越狠，切完的 hold 要比平常更长。
+
+## 两式选型
+| 式 | 做法 | 适用 |
+|----|------|------|
+| A beat-cut-accelerando 递进硬切串 | 六视图按 16→12→8→6→4f 间隔减半全屏硬切，加速逼近，末刀戛然定格回主画面轻推收住 | 冲刺逼近感：预告片式蓄力、功能连打冲向结论 |
+| B paparazzi-flash 连闪定格 | 三次白闪各硬切同素材不同裁切（全景→卡片特写→数字特写），快门余韵沉降，第三闪停在数字收束 | 高光时刻仪式感：颁奖连拍、关键数字的加冕 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| A 切点帧 | 0/49/65/77/85/91/95（建立 49f，间隔 16→12→8→6→4f） | 间隔按"减半律"缩，等差缩读不出加速；末间隔 <4f 肉眼跟不上 |
+| A 视图池 | 6 个 = 两块 FakeDashboard × scale 1/1.8/2.6 + 对焦点，transformOrigin 钉焦点再平移居中 | 视图必须是同一产品的不同构图（语义连续），六个无关画面读作故障 |
+| A 切帧快门感 | 切帧 1f brightness 1.05 + 叠 6% 不透明度白层 | 只在切帧亮一下，是"咔"不是闪光灯；再厚就抢了 B 式的活 |
+| A 末段收住 | 定格回主画面 hold 35f，scale 1→1.06 ease-out 慢推 20f 后静止 | 戛然而止是这式的句号——末刀后不许再有任何切 |
+| B 三闪切点 | 30/52/70（间隔 22f→18f 渐紧），闪前 30f 慢推"活素材"衬托闪后定格 | 闪前必须是活的，全片死素材三闪读不出"定格" |
+| B 白闪层 | 每闪 opacity 0.95→0 走 4f ease-out 衰减；闪帧 ±2px seed 哈希全屏抖动 | 0.95 起步才有闪光灯的爆点；衰减 >6f 变柔光转场，失去快门感 |
+| B 快门余韵 | 切入视图 scale 1.03→1 走 6f ease-out 回落 + −16px 沉降归零 | 余韵是"被拍到晃了一下"；去掉后三闪读作幻灯片翻页 |
+| B 三裁切 | 同一 Footage 换 scale/transformOrigin：1.0 全景 / 2.3 卡片 / 4.0 数字 | 层层逼近有叙事方向；乱序（特写→全景→特写）读作剪错 |
+| B 末段收束 | 第三闪后数字特写 hold 60f 静止 | 三闪是重击，hold 要给足平常两倍以上 |
+
+## 已知坑
+- **demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验**
+- 两式都是**声音强依赖**手法：切点必须钉在音轨拍点上，每切一声
+  tick（A）/ 快门咔嚓（B），无声版只剩画面乱跳；钉帧走
+  sound-design.md §4.5 相对 shot 起点，不钉绝对帧
+- A 式六视图要"同一产品的不同构图"而非六个无关画面——观众要在加速
+  中始终认得这是谁；跨产品/跨场景的素材别用这式
+- 切串全片 ≤1 次（P4 克制原则）：这是全片最响的一记，第二次出现
+  第一次就白打了
+- 节奏偏好判例是单向"放慢"，本卡是刻意例外——切完的 hold（A 35f /
+  B 60f）是底线不是建议，宁多勿少
+- 真硬切 = frame 落区间渲染对应视图，无任何过渡帧；手滑加 2f 交叉
+  淡化就不是硬切了，节拍感立即糊掉
+
+## 参考实现
+demos/beat-cut-moves/
+（BeatCutAccelerando.tsx / PaparazziFlash.tsx）

package/skills/hyper-animator-codex/references/shotcraft/cards/beat-step-list-theme-cycle/README.md

@@ -0,0 +1,59 @@
+---
+name: beat-step-list-theme-cycle
+一句话: 三通道节拍器——深色场形容词列表逐拍上移一行，视口中央固定胶囊"接住"下一个词并换色，整场底色同拍跟换；行、色、场三通道锁死同一拍点
+适用: "同一产品多种气质/多主题展示"段落（modern/playful/expressive 式形容词连打）；全片节奏最密的一段；音乐段对拍
+时长: 铺垫 30f + 每拍 18f × 拍数 + 收尾 hold；3 拍约 3.5s（demo 110f）
+能量: 高（0.6s 一拍三通道齐跳，密度型高能）
+---
+
+## 意图
+换一次主题色是功能演示；0.6 秒换一次、连换三次、每次"选中行+胶囊色
++全场底色"三件事同帧齐跳——就成了节拍器。用最便宜的变量切换做出
+全片最高的节奏密度。命门有二：一是**三通道必须锁同一拍点**，任何
+一通道慢半拍，"齐跳"退化成三个各自为政的动画；二是**跳与滑的分界**
+——跳变只占拍头 6f，其余 12f 完全静置，拍点要"跳"不要"滑"，
+匀速滚动的列表就只是列表。
+
+## 动效核心
+- 胶囊固定在视口中央行**不动**，列表 translateY 逐拍步进——视觉上
+  读作"胶囊跳到下一行接住新词"，实际动的是世界不是胶囊
+- 拍长 18f（0.6s @30fps ≈ 100BPM），跳变窗仅拍头 6f：
+  `snap(t) = 1-(1-x)^3.2`（陡 ease-out），其余帧静置
+- 三通道同源驱动：同一个 tInBeat 同时喂列表位移、胶囊/底色
+  rgb 逐通道 cross-mix、胶囊 squash——一个时钟，不许各挂各的曲线
+- 主题表逐拍换对（demo：灰白/深棕→绿→紫→红/深藏青），胶囊色与
+  底色是配好的深浅对，不是独立随机色
+- 胶囊落位 squash：scale 1.12→0.97→1 随拍头 6f 走完
+- 选中词反白、非选中词 34% 白；上下各 300px 底色渐变羽化收视口
+  ——羽化色必须跟 bgColor 实时同步，写死颜色换场时穿帮
+- 开拍前 30f 静置铺垫——先让观众看清"这是个列表"，再开始打拍
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 拍长 | 18f（BEAT_LEN，改它即改 BPM 对音轨） | <12f 观众来不及读词只见闪色；>26f 拍感散成逐个展示 |
+| 跳变窗 | 拍头 6f，ease-out 指数 3.2 | 窗 >10f 或缓曲线，"跳"变"滑"，节拍器塌成滚动列表 |
+| 拍数 | 3–4 拍 | 5+ 拍观众适应了节奏开始走神；1–2 拍立不起"节拍器"人设 |
+| squash | 1.12→0.97→1 | 去掉它胶囊像贴图换色；>1.2 弹跳抢了换色的戏 |
+| 底色跨度 | 相邻主题底色须同明度不同色相（都深色） | 明度跳变（深→浅）会读作闪屏而非换肤 |
+| 铺垫/收尾 | 前 30f 静置；末拍后 hold ≥30f | 没铺垫第一拍读作 bug；末拍即切没有"停在最终色"的确认 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 与 theme-switch-moves 分工：那卡是单次换肤的仪式（扫场/涟漪，换一次
+  讲一次故事），本卡是连续多次换肤当节拍用——讲"深色模式功能"用那卡，
+  讲"多气质/多主题体量"用本卡
+- 与 cel-flash-stomp 同为高密度拍点段，同片二选一或隔远——都是
+  "每 0.6s 一记"的手法，紧邻观众会拍疲劳
+- **声音强依赖**：拍点对齐鼓点（换 BEAT_LEN 对 BPM），无声版三通道
+  齐跳读作界面抽风
+- 词表长度 ≥ 拍数+2——列表底部要留未选中的词垫着，最后一拍就停在
+  列表末行会露出"下面没了"
+- 反白判定跟 beat 整数走、颜色跟 tInBeat 小数走（demo 即如此）——
+  两者都跟小数会出现半白半灰的中间态词
+
+## 参考实现
+demos/beat-step-list-theme-cycle/
+（BeatStepListThemeCycle.tsx）
+原片出处：bear-app 22.3–24.6s

package/skills/hyper-animator-codex/references/shotcraft/cards/before-after-slider-scrub/README.md

@@ -0,0 +1,47 @@
+---
+name: before-after-slider-scrub
+一句话: 前后对比拉杆——"处理前/后"两版叠放，分割杆先猛甩后慢扫，杆过处新版"显影"揭出
+适用: AI 增强/优化/重构类功能的效果对比段落（"用前 vs 用后"一镜讲清）
+时长: 4–5s
+能量: 中（快甩是打击点，慢扫是阅读期）
+---
+
+## 意图
+AI 图像产品发布片的标准对比语法：同一画面"处理前"（低对比灰蒙）
+与"处理后"（清晰版）叠放，带圆手柄的竖分割杆先从左端猛甩到 70%
+（overshoot 回弹）、停一拍，再以约 1/5 的速度慢扫回来让观众看清
+差异——**快甩慢扫的速度对比就是节奏**：快甩宣告"变了"，
+慢扫证明"变在哪"。
+
+## 动作阶段
+| 阶段 | 帧段参考 | 内容 |
+|------|------|------|
+| 1 静置 | f0–14 | 杆停 8%，画面几乎全是"处理前" |
+| 2 快甩 | 12f | 8%→76%（out cubic）过冲 |
+| 3 回弹 | 12f | 76%→70% |
+| 4 停顿 | ~18f | 让观众看清 after |
+| 5 慢扫 | ~48f | 70%→40% 二次展示差异 |
+| 6 定格 | 末 ≥40f | 真静止 |
+
+## 参数表
+| 参数 | 典型值 | 调节手感 |
+|------|--------|----------|
+| 速度比 | 快甩 12f vs 慢扫 48f，约 5:1 | 比例 <3:1 节奏对比不可感 |
+| 揭示 | after 层 clip-path inset 右边界跟随杆 x | 杆和揭示边界错位即穿帮 |
+| 手柄 | 圆形手柄 + 速度差分驱动 scaleX 微拉伸（峰值 1.18），静止自动归 1 | 拉伸给手柄"被甩"的重量感 |
+| before 处理 | 低对比灰蒙版 | before 太难看是自黑，"差"要可信（真实旧版/未优化态） |
+| 角标 | BEFORE/AFTER 角标放内容区 | demo 判例：初版压住侧栏/头像穿帮 |
+
+## 已知坑
+- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
+  首次实战须以真实素材回验
+- 两版必须同布局同机位——布局不同读作两个页面，对比失效
+  （theme-switch-moves 同款约束）
+- 实战 before/after 都用真实截图（Q1）：before 是注入旧数据/关闭
+  功能的真实态，不手搓"故意丑"的假 before
+- 慢扫终点停 40% 而非 0%——留一段 after 在画面上定格（结论可见）
+- 声音：快甩一声 whoosh + 回弹轻 tick，慢扫无声或极轻摩擦音（S4）
+
+## 参考实现
+demos/before-after-slider-scrub/
+（BeforeAfterSliderScrub.tsx）