npm - @baimingtao/lbs-agent - Versions diffs - 1.0.0 - Mend

@baimingtao/lbs-agent 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1114) hide show

package/extensions/skills/optional/creative/hyperframes/references/composition.md ADDED Viewed

@@ -0,0 +1,129 @@
+# 构图 Authoring
+HTML structure、data attributes、timeline contract 以及不可协商的规则。
+## Root Structure
+独立的 `index.html` —— 顶层构图。**不要使用 `<template>`**。将 `data-composition-id` div 直接放在 `<body>` 中。
+```html
+<!doctype html>
+<html>
+  <body>
+    <div
+      id="stage"
+      data-composition-id="root"
+      data-start="0"
+      data-duration="10"
+      data-width="1920"
+      data-height="1080"
+    >
+      <!-- clips go here -->
+      <video id="clip-1" data-start="0" data-duration="5" data-track-index="0" src="intro.mp4" muted playsinline></video>
+      <img id="logo" data-start="2" data-duration="3" data-track-index="1" src="logo.png" />
+      <audio id="music" data-start="0" data-duration="10" data-track-index="2" data-volume="0.5" src="music.wav"></audio>
+    </div>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      tl.from("#logo", { opacity: 0, y: 40, duration: 0.6 }, 2);
+      window.__timelines["root"] = tl;
+    </script>
+  </body>
+</html>
+```
+通过 `data-composition-src` 加载的子构图**必须**使用 `<template>`：
+```html
+<template id="my-comp-template">
+  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+    <!-- content + scoped <style> + <script> with window.__timelines["my-comp"] -->
+  </div>
+</template>
+```
+从 root 加载：`<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
+## Data Attributes
+### 所有 clips
+| Attribute | 必需 | 值 |
+| ------------------ | --------------------------------- | ------------------------------------------------------ |
+| `id` | Yes | 唯一标识符 |
+| `data-start` | Yes | 秒数，或 clip ID 引用（`"el-1"`、`"intro + 2"`） |
+| `data-duration` | img/div/compositions 必需 | 秒数。Video/audio 默认为媒体时长。 |
+| `data-track-index` | Yes | 整数。同一 track 上的 clips 不能重叠。 |
+| `data-media-start` | No | 裁剪进入源媒体的偏移量（秒） |
+| `data-volume` | No | 0–1（默认为 1） |
+`data-track-index` 仅控制 timeline 布局 —— **不控制**视觉层级。请使用 CSS 的 `z-index` 控制层级。
+### 构图 clips
+| Attribute | 必需 | 值 |
+| ---------------------------- | -------- | -------------------------------------------- |
+| `data-composition-id` | Yes | 唯一的构图 ID |
+| `data-start` | Yes | 开始时间（root composition：`"0"`） |
+| `data-duration` | Yes | 优先级高于 GSAP timeline 时长 |
+| `data-width` / `data-height` | Yes | 像素尺寸 (1920x1080 或 1080x1920) |
+| `data-composition-src` | No | 外部 HTML 文件的路径 |
+## Timeline Contract
+- 每个 timeline 都以 `{ paused: true }` 开始 —— 由播放器控制播放。
+- 注册每个 timeline：`window.__timelines["<composition-id>"] = tl`。
+- 时长来源于 `data-duration`，而不是 GSAP timeline 的长度。
+- 框架会自动嵌套子 timeline —— 不要手动添加它们。
+- 绝对不要为了设置时长而创建空的 tween。
+## Non-Negotiable Rules
+1. **确定性。** 禁止使用 `Math.random()`、`Date.now()` 或基于时间的逻辑。如果需要伪随机性，请使用带种子的 PRNG（例如 mulberry32）。
+2. **GSAP 仅用于视觉属性。** `opacity`、`x`、`y`、`scale`、`rotation`、`color`、`backgroundColor`、`borderRadius`、transforms。绝对不要用于动画化 `visibility`、`display`，或调用 `video.play()`/`audio.play()`。
+3. **跨 timeline 无属性冲突。** 绝对不要在多个 timeline 中同时为同一个元素的同一个属性设置动画。
+4. **禁止 `repeat: -1`。** 无限重复的 tween 会破坏捕获引擎。请计算 `repeat: Math.ceil(duration / cycleDuration) - 1`。
+5. **同步构建 timeline。** 绝对不要在 `async`/`await`、`setTimeout` 或 Promises 中构建 timeline。捕获引擎会在页面加载后同步读取 `window.__timelines`。字体由编译器嵌入 —— 无需等待加载。
+6. **Root composition 不使用 `<template>` 包裹。** 只有子构图使用 `<template>`。
+7. **Video 必须始终为 `muted playsinline`。** Audio 必须始终是独立的 `<audio>` 元素 —— 即使是同一个源文件。
+8. **内容容器使用 padding，而不是绝对定位。** `.scene-content { width: 100%; height: 100%; padding: Npx; display: flex; flex-direction: column; gap: Npx; box-sizing: border-box }`。绝对定位的内容容器会溢出。请将 `position: absolute` 仅保留给装饰性元素。
+## Scene Transitions
+多场景构图必须遵循以下所有规则：
+1. **场景之间必须始终使用过渡。** 禁止硬切。
+2. **必须始终为每个场景元素使用入场动画。** 每个元素都通过 `gsap.from(...)` 动画进入。任何元素都不能以最终状态直接出现。
+3. **绝对不要使用出场动画**（最后一场除外）。这意味着禁止使用 `gsap.to()` 将 `opacity` 动画化为 0，或将 `y` 移出屏幕等。过渡即是出场。在过渡开始的那一刻，正在离场的场景内容必须完全可见。
+4. **仅限最终场景：** 可以将元素淡出。这是唯一允许使用 `gsap.to(..., { opacity: 0 })` 的场景。
+## Typography and Assets
+- **字体：** 在 CSS 中写下你想要的 `font-family` —— 编译器会自动嵌入支持的字体。不支持的字体会产生编译器警告。
+- 为外部媒体添加 `crossorigin="anonymous"`。
+- 对于动态文本大小调整，请使用 `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`。
+- 所有项目文件都位于项目根目录下的 `index.html` 旁边。子构图使用 `../` 引用资产。
+- 对于渲染为视频：60px+ 标题，20px+ 正文，16px+ 数据标签。数字列使用 `font-variant-numeric: tabular-nums`。避免在深色背景上使用全屏线性渐变（H.264 色带瑕疵 —— 请使用径向渐变或纯色 + 局部发光）。
+## Animation Guardrails
+- 将第一个动画偏移 0.1–0.3s（不要从 `t=0` 开始）。
+- 在入场 tween 中变换缓动效果 —— 每个场景至少使用 3 种不同的缓动。
+- 不要在同一个场景内重复入场模式。
+## Never Do
+1. 忘记注册 `window.__timelines`。
+2. 用 video 播放 audio —— 必须始终使用静音的 video + 独立的 `<audio>`。
+3. 将 video 嵌套在定时的 div 中 —— 请使用未定时的包裹器。
+4. 使用 `data-layer`（请使用 `data-track-index`）或 `data-end`（请使用 `data-duration`）。
+5. 对 video 元素的尺寸进行动画处理 —— 请改为对一个包裹器 div 进行动画处理。
+6. 在媒体上调用 `play`/`pause`/`seek` —— 播放由框架控制。
+7. 创建没有 `data-composition-id` 的顶层容器。
+8. 在任何 timeline 或 tween 上使用 `repeat: -1`。
+9. 异步构建 timeline。
+10. 对后续场景中的元素使用 `gsap.set()` —— 在页面加载时它们还不存在于 DOM 中。请在 timeline 内部，于 clip 的 `data-start` 处或之后使用 `tl.set(selector, vars, timePosition)`。
+11. 在内容文本中使用 `<br>` —— 当文本自动换行时会导致不必要的额外换行。请改用 `max-width`。例外情况：简短的展示标题（例如 "THE\nIMMORTAL\nGAME"），这种情况下每个单词都被刻意放在单独的一行。

package/extensions/skills/optional/creative/hyperframes/references/features.md ADDED Viewed

@@ -0,0 +1,289 @@
+# HyperFrames 特性 参考
+当合成需要字幕、TTS 解说、音频反应视觉效果、标记风格的文本高亮或场景过渡时，请加载此文件。这里的所有模式都是确定性的（没有 `Math.random()`，没有 `Date.now()`，没有运行时音频分析），并且与其余合成内容位于同一个 GSAP 时间线上。
+## Captions
+### 语言规则（不可商量）
+**除非音频已确认是英文，否则绝不使用 `.en` whisper 模型。** `.en` 模型会将非英文音频翻译成英文，而不是进行转录。
+- 用户指明了语言 → `npx hyperframes transcribe audio.mp3 --model small --language <code>`（不包含 `.en`）
+- 用户确认是英文 → `--model small.en`
+- 语言未知 → `--model small`（自动检测）
+### 风格检测
+如果用户没有指定字幕样式，请根据转录文本的语气进行检测：
+| 语气 | 字体风格 | 动画 | 颜色 | 大小 |
+| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
+| 激昂 / 发布 | 粗体压缩，800-900 | Scale-pop, `back.out(1.7)`, 0.1-0.2s | 深色背景上的亮色 | 72-96px |
+| 企业 | 干净的无衬线，600-700 | 淡入+滑动, `power3.out`, 0.3s | 白色 / 中性色 + 柔和的强调色 | 56-72px |
+| 教程 | 等宽 / 干净的无衬线，500-600 | 打字机或淡入，0.4-0.5s | 高对比度，极简 | 48-64px |
+| 叙事 | 衬线 / 优雅，400-500 | 缓慢淡入，`power2.out`, 0.5-0.6s | 温暖柔和的色调 | 44-56px |
+| 社交 | 圆润的无衬线，700-800 | 跳跃，`elastic.out`，逐词出现 | 活泼的彩色胶囊 | 56-80px |
+### 词语分组
+- 高能量：2-3 个词，快速切换。
+- 日常对话：3-5 个词，自然短语。
+- 沉稳 / 平静：4-6 个词。
+在句子边界、150ms 以上的停顿处，或达到最大词数时断句。
+### 定位
+- 横屏 (1920x1080)：底部 80-120px，居中。
+- 竖屏 (1080x1920)：距离底部约 600-700px，居中。
+- 绝不要遮挡主体的面部。使用 `position: absolute`（绝不使用 relative）。同一时间只显示一组字幕。
+### 防止文本溢出
+使用运行时助手可以防止字幕溢出：
+```js
+const result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
+  fontFamily: "Outfit",
+  fontWeight: 900,
+  maxWidth: 1600, // 1600 横屏，900 竖屏
+});
+el.style.fontSize = result.fontSize + "px";
+```
+当逐词样式使用 `scale > 1.0` 时，计算 `maxWidth = safeWidth / maxScale` 以留出余量。容器需要 `overflow: visible`（不要用 `hidden` —— hidden 会裁剪被缩放的强调词和发光效果）。
+### 字幕退出保证
+每组字幕必须在其退出 tween 后强制清除——否则字幕组会残留并影响后续内容：
+```js
+tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
+tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // 确定性清除
+```
+### 逐词样式
+扫描转录文本，找出需要特殊处理的词语：
+- 品牌 / 产品名称——更大，独特的颜色。
+- 全大写——缩放增强，闪烁，强调色。
+- 数字 / 统计数据——加粗，强调色。
+- 情感关键词——夸张的动画（过冲、反弹）。
+- 号召性用语——高亮、下划线、颜色突出。
+## TTS (Kokoro-82M)
+本地运行，无需 API 密钥。在 CPU 上运行。首次使用时下载模型（约 311 MB + 约 27 MB 语音，缓存在 `~/.cache/hyperframes/tts/`）。
+### 语音选择
+| 内容类型 | 语音 | 原因 |
+| ------------- | ----------------------- | --------------------------- |
+| 产品演示 | `af_heart` / `af_nova` | 温暖，专业 |
+| 教程 | `am_adam` / `bf_emma` | 中性，容易跟上 |
+| 营销 | `af_sky` / `am_michael` | 充满活力或权威感 |
+| 文档 | `bf_emma` / `bm_george` | 清晰的英式英语 |
+| 休闲 | `af_heart` / `af_sky` | 亲切，自然 |
+运行 `npx hyperframes tts --list` 获取涵盖 8 种语言的全部 54 种语音。
+### 多语言音素化
+语音 ID 的首字母指示了语言：`a`=美式英语，`b`=英式英语，`e`=西班牙语，`f`=法语，`h`=印地语，`i`=意大利语，`j`=日语，`p`=巴西葡萄牙语，`z`=普通话。CLI 会根据该前缀自动推断音素器（phonemizer）区域设置——当语音和文本匹配时，你不需要 `--lang`。
+```bash
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "今日はいい天気ですね"            --voice jf_alpha --output ja.wav
+```
+仅在需要覆盖自动检测（例如风格化的口音）时才传入 `--lang`：
+```bash
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+```
+有效的 `--lang` 代码：`en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`。非英语的音素化需要在系统范围内安装 `espeak-ng`（`apt-get install espeak-ng` / `brew install espeak-ng`）。
+### 语速
+- `0.7-0.8` — 教程，复杂内容
+- `1.0` — 自然（默认）
+- `1.1-1.2` — 片头，轻快内容
+- `1.5+` — 极少适用
+### TTS + Captions 工作流
+```bash
+npx hyperframes tts script.txt --voice af_heart --output narration.wav
+npx hyperframes transcribe narration.wav   # → transcript.json (word-level)
+```
+## 音频反应视觉效果
+根据音乐、人声或音效驱动视觉效果。任何支持 GSAP tween 的属性都可以对预提取的音频数据做出反应。
+### 数据格式
+```js
+const AUDIO_DATA = {
+  fps: 30,
+  totalFrames: 900,
+  frames: [{ bands: [0.82, 0.45, 0.31, /* ... */] }, /* ... */],
+};
+```
+`frames[i].bands[]` 是频带振幅，范围 0-1。索引 0 = 低音，更高的索引 = 高音。每个频带都在整条音轨中进行了独立归一化。
+### 将音频映射到视觉效果
+| 音频信号 | 视觉属性 | 效果 |
+| ---------------------- | --------------------------------- | -------------------------- |
+| 低音 (`bands[0]`) | `scale` | 节拍脉动 |
+| 高音 (`bands[12-14]`) | `textShadow`, `boxShadow` | 发光强度 |
+| 整体振幅 | `opacity`, `y`, `backgroundColor` | 呼吸、上浮、颜色偏移 |
+| 中频 (`bands[4-8]`) | `borderRadius`, `width` | 形状变形 |
+任何支持 GSAP tween 的属性都有效——`clipPath`、`filter`、SVG 属性、CSS 自定义属性。让内容引导视觉，让音频驱动行为。**绝不添加**均衡器条、频谱分析仪、波形显示、彩虹循环或普通的粒子系统——它们看起来很廉价。
+### 采样模式（必需）
+音频反应需要通过 `tl.call()` 的 `for` 循环进行逐帧采样，而不是单一的 tween。单个长 tween 不会对音频做出反应：
+```js
+for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    ((frame) => () => draw(frame))(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+```
+### 注意事项
+- **在容器上使用 textShadow** 且子元素是半透明的（例如处于非活动状态的字幕词为 `rgba(255,255,255,0.3)`），会在每个子元素后面渲染出可见的发光矩形。请将发光效果单独应用于活动词，而不是应用于容器。
+- **文本需保持克制** —— 3-6% 的缩放变化，柔和发光。剧烈的脉动会使文本无法阅读。
+- **非文本元素可以更夸张** —— 背景和形状可以承受 10-30% 的波动。
+- **仅限确定性** —— 预提取的音频数据，不使用 Web Audio API，无运行时分析。
+## 标记风格高亮
+使用确定性的 CSS + GSAP 实现经典的“高亮 / 圈选 / 迸发 / 涂鸦 / 勾画”绘制模式以强调文本。完全支持随机定位（Seekable）——没有动画式 SVG 滤镜，也没有 JS 定时器。
+### Highlight (黄色标记扫过)
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+```css
+.mh-highlight-wrap { position: relative; display: inline; }
+.mh-highlight-bar {
+  position: absolute; inset: 0 -6px;
+  background: #fdd835; opacity: 0.35;
+  transform: scaleX(0); transform-origin: left center;
+  border-radius: 3px; z-index: 0;
+}
+.mh-highlight-text { position: relative; z-index: 1; }
+```
+```js
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+```
+多行：应用于 `.mh-highlight-bar` 并使用 `stagger: 0.3`。
+### Circle (圈选)
+围绕单词绘制手绘风格的椭圆。使用带有 `border-radius: 50%` 的定位 `::before` 伪元素，轻微旋转，并利用 `clip-path` 避免遮挡字母。在内联 SVG 圆圈上为 `clip-path` 或 `stroke-dashoffset` 添加动画。
+### Burst (迸发)
+单词周围呈辐射状的短线。渲染 6-12 个定位成放射状的小 `<span>` 元素；为 `scaleY` 添加从 0 开始的动画。
+### Scribble (涂鸦)
+通过对内联 SVG `<path>`（其 `d` 属性描述锯齿状路径）的 `stroke-dashoffset` 进行动画来创建混乱的覆盖层。使用种子值，绝不使用 `Math.random()`。
+### Sketchout (勾画)
+粗略的矩形轮廓。两个带有轻微 `transform` 偏移的 `<rect>`，通过 `stroke-dashoffset` 添加动画。
+所有这五种模式仅对 CSS transforms 或 `stroke-dashoffset` 进行动画——这两者都能平滑地进行 tween，具有确定性，并且能正确地进行定位（seek）。
+## 场景过渡
+每一个多场景合成都必须使用过渡。不要使用生硬的跳剪。
+### 能量 → 主要过渡
+| 能量 | CSS 主要过渡 | Shader 主要过渡 | 强调过渡 | 持续时间 | 缓动 |
+| ------------------------------------ | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ------------------------ |
+| **平静** (健康、品牌、奢侈) | 模糊淡入淡出，焦点转换 | 交叉扭曲变形，热变形 | 漏光，圆形光圈 | 0.5-0.8s | `sine.inOut`, `power1` |
+| **中等** (企业、SaaS) | 平移滑动，交错方块 | 快速平移，电影级缩放 | 挤压，垂直推挤 | 0.3-0.5s | `power2`, `power3` |
+| **高** (促销、体育、发布) | 穿越缩放，过曝 | 脊状燃烧，故障，色差分裂 | 交错方块，重力掉落 | 0.15-0.3s | `power4`, `expo` |
+选择一种主要过渡（占场景切换的 60-70%）加上 1-2 种强调过渡。绝不在每个场景都使用不同的过渡。
+### 情绪 → 过渡类型
+| 情绪 | 过渡 |
+| ------------------------ | --------------------------------------------------------------------------- |
+| 温暖 / 诱人 | 漏光，模糊淡入淡出，焦点转换，胶片燃烧 · _Shader:_ 热变形，交叉扭曲变形 |
+| 冷漠 / 临床 | 挤压，缩小，百叶窗，快门，网格溶解 · _Shader:_ 引力透镜 |
+| 编辑 / 杂志风 | 平移滑动，垂直推挤，对角分割，快门 · _Shader:_ 快速平移 |
+| 科技 / 未来感 | 网格溶解，交错方块，百叶窗 · _Shader:_ 故障，色差分裂 |
+| 紧张 / 前卫 | 故障，VHS，色差，波纹 · _Shader:_ 脊状燃烧，域扭曲 |
+| 活泼 / 有趣 | 弹性推挤，3D 翻转，圆形光圈，变形圆圈 · _Shader:_ 旋转漩涡，波纹 |
+| 戏剧性 / 电影感 | 穿越缩放，重力掉落，过曝 · _Shader:_ 电影级缩放，引力透镜 |
+| 高端 / 奢华 | 焦点转换，模糊淡入淡出，色彩渐黑 · _Shader:_ 交叉扭曲变形 |
+| 复古 / 模拟 | 胶片燃烧，漏光，VHS，时钟擦除 · _Shader:_ 漏光 |
+### 预设
+| 预设 | 持续时间 | 缓动 |
+| ---------- | -------- | ----------------- |
+| `snappy` | 0.2s | `power4.inOut` |
+| `smooth` | 0.4s | `power2.inOut` |
+| `gentle` | 0.6s | `sine.inOut` |
+| `dramatic` | 0.5s | `power3.in` → out |
+| `instant` | 0.15s | `expo.inOut` |
+| `luxe` | 0.7s | `power1.inOut` |
+### 安装 a shader transition
+```bash
+npx hyperframes add flash-through-white
+npx hyperframes add --list
+```
+### CSS 与 shader
+- **CSS 过渡** 通过 opacity、transform、`clip-path` 和滤镜对场景容器进行动画。设置更简单。
+- **Shader 过渡** 在 WebGL 画布上逐像素合成两种场景纹理——可以完成 CSS 无法实现的扭曲、溶解和变形。从 `@hyperframes/shader-transitions` 导入，而不是编写原始的 GLSL。
+不要在同一个合成中混用 CSS 和 shader 过渡——一旦合成使用了 shader 过渡，WebGL 画布就会在每次过渡时取代基于 DOM 的场景切换。
+### 兼容 Shader 的 CSS 规则
+Shader 过渡通过 html2canvas 将 DOM 场景捕获为 WebGL 纹理。Canvas 2D 管道与 CSS 并不完全匹配：
+1. 渐变中不要使用 `transparent` 关键字——在 alpha 值为零时使用目标颜色：用 `rgba(200,117,51,0)` 代替 `transparent`。（Canvas 会将 `transparent` 解析为 `rgba(0,0,0,0)` 从而产生暗色边缘。）
+2. 厚度小于 4px 的元素不要使用渐变背景。在细小的强调线上使用纯色的 `background-color`。
+3. 在捕获期间可见的元素上不要使用 CSS 变量（`var()`）——html2canvas 无法稳定地解析自定义属性。请使用字面颜色值。
+4. 用 `data-no-capture` 标记无法捕获的装饰性元素——它们会保留在活动 DOM 中，但在 shader 纹理中不存在。
+5. 渐变的不透明度不要低于 0.15——在 canvas 和 CSS 中的渲染效果不同。
+6. 每个 `.scene` div 必须具有明确的 `background-color`，并在 `init()` 配置中传入相同的颜色作为 `bgColor`。缺少任何一个，纹理都会渲染为黑色。
+这些规则仅适用于 shader 过渡合成。仅使用 CSS 的合成没有任何限制。
+### 禁止事项
+- 在同一个合成中混用 CSS 和 shader 过渡。
+- 在除了最终场景之外的任何场景上使用退场动画——过渡本身就是退场。
+- 每个场景引入一种新的过渡类型——选择一种主要过渡 + 1-2 种强调过渡。
+- 使用会产生可见几何重复的过渡（网格、六边形单元、均匀的圆点）——无论其背后的数学原理如何，它们看起来都很假。首选有机噪声（FBM，域扭曲）。

package/extensions/skills/optional/creative/hyperframes/references/gsap.md ADDED Viewed

@@ -0,0 +1,136 @@
+# GSAP for HyperFrames
+GSAP 是所有 HyperFrames 合成的动画引擎。在合成内部通过 CDN 加载：
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+```
+## 核心 Tween 方法
+- **`gsap.to(targets, vars)`** — 从当前状态动画到 `vars`。最常用。
+- **`gsap.from(targets, vars)`** — 从 `vars` 动画到当前状态（适用于入场动画）。
+- **`gsap.fromTo(targets, fromVars, toVars)`** — 明确指定起始和结束状态。
+- **`gsap.set(targets, vars)`** — 立即应用（duration 为 0）。不要对稍后才入场的 clip 元素使用此方法 —— 应该在 timeline 中使用 `tl.set(selector, vars, time)`。
+始终使用 **camelCase** 属性名（例如 `backgroundColor`、`rotationX`，而不是 `background-color`）。
+## 常用 vars
+- **`duration`** — 秒（默认 0.5）。
+- **`delay`** — 开始前的延迟秒数。
+- **`ease`** — `"power1.out"`（默认）、`"power3.inOut"`、`"back.out(1.7)"`、`"elastic.out(1, 0.3)"`、`"none"`、`"expo.out"`、`"circ.inOut"`。
+- **`stagger`** — 数字 `0.1` 或对象：`{ amount: 0.3, from: "center" }`、`{ each: 0.1, from: "random" }`。
+- **`overwrite`** — `false`（默认）、`true` 或 `"auto"`。
+- **`repeat`** — 数字（在 HyperFrames 中绝不可设为 `-1`）。**`yoyo`** — 每次重复时交替动画方向。
+- **`onComplete`**、**`onStart`**、**`onUpdate`** — 回调函数。
+- **`immediateRender`** — 在 `from()`/`fromTo()` 中默认为 `true`。如果后续有针对相同元素和属性的 tween，请将其设为 `false`，以避免出现覆盖异常。
+## Transforms
+优先使用 GSAP 的 transform 别名，而不是原生的 CSS `transform`：
+| GSAP property | Equivalent |
+| --------------------------- | -------------------------- |
+| `x`, `y`, `z` | translateX/Y/Z (px) |
+| `xPercent`, `yPercent` | translateX/Y (%) |
+| `scale`, `scaleX`, `scaleY` | scale |
+| `rotation` | rotate (deg) |
+| `rotationX`, `rotationY` | 3D rotate |
+| `skewX`, `skewY` | skew |
+| `transformOrigin` | transform-origin |
+- **`autoAlpha`** — 优先使用它而不是 `opacity`。当值为 0 时，还会同时设置 `visibility: hidden`。
+- **CSS variables** — `"--hue": 180`。
+- **Directional rotation** — `"360_cw"`、`"-170_short"`、`"90_ccw"`。
+- **`clearProps`** — `"all"` 或以逗号分隔；在动画完成时移除内联样式。
+- **Relative values** — `"+=20"`、`"-=10"`、`"*=2"`。
+## 基于函数的值
+```js
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  stagger: 0.1,
+});
+```
+## Easing
+内置的 ease 效果包括：`power1` 到 `power4`、`back`、`bounce`、`circ`、`elastic`、`expo`、`sine`。每种都支持 `.in`、`.out` 和 `.inOut` 变体。
+经验法则：
+- 入场：`power3.out`、`expo.out`、`back.out(1.4)`
+- 出场：`power2.in`、`expo.in`
+- Scrubbed 区间：`none`（线性）
+- 丰富同一个场景中各个入场 tween 的 ease 效果 —— 至少使用 3 种不同的 ease。
+## 默认值
+```js
+gsap.defaults({ duration: 0.6, ease: "power2.out" });
+```
+## Timelines（HyperFrames 主要模式）
+```js
+window.__timelines = window.__timelines || {};
+const tl = gsap.timeline({ paused: true, defaults: { duration: 0.6, ease: "power2.out" } });
+tl.from(".title",    { y: 50, opacity: 0 }, 0.3);
+tl.from(".subtitle", { y: 30, opacity: 0 }, 0.5);
+tl.from(".cta",      { scale: 0.8, opacity: 0, ease: "back.out(1.7)" }, 0.8);
+window.__timelines["root"] = tl;
+```
+### Position 参数
+作为 `.from()` / `.to()` / `.add()` 的第三个参数：
+- 绝对秒数：`0.5`、`2.1`。
+- 相对于前一个动画的结束时间：`">+0.2"`（前一个结束后 0.2 秒）、`"<"`（与前一个同时）、`"<+0.3"`（前一个开始后 0.3 秒）。
+- 命名标签：`tl.addLabel("act2", 5); tl.from(".x", { y: 30 }, "act2");`
+### 嵌套
+HyperFrames 会自动嵌套子合成的 timeline。**不要**手动调用 `tl.add(subTl)` —— 框架会自动根据子合成的 `data-start` 将子 timeline 接入到父级中。
+### 播放控制
+播放过程由播放器控制。在构建时不要调用 `tl.play()`、`tl.pause()` 或 `tl.reverse()`。必须配置 `{ paused: true }`。
+## Stagger
+```js
+// 均匀分布
+tl.from(".card", { opacity: 0, y: 40, stagger: 0.1 });
+// 控制总时长
+tl.from(".card", { opacity: 0, stagger: { amount: 0.6, from: "center" } });
+// 确定性的“随机”交错（HyperFrames 合成必须具备确定性）
+tl.from(".dot", { opacity: 0, stagger: { each: 0.05, from: "random" } });
+```
+`stagger.from`：可以是 `"start"` | `"end"` | `"center"` | `"edges"` | `"random"` | 索引数字 | 用于网格的 `[x, y]`。
+## 性能
+- 动画 transforms（`x`、`y`、`scale`、`rotation`、`opacity`） —— 性能开销小，支持 GPU 加速。
+- 避免对 `width`、`height`、`top`、`left`、`margin` 进行动画 —— 会引发频繁的排版重计算。
+- 避免在大型元素上使用 box-shadow 或 filter 动画 —— 性能开销极大。
+- 极少需要用到 `will-change`；GSAP 会自动处理层级提升。
+## gsap.matchMedia（在 HyperFrames 中极少使用）
+合成的尺寸是固定的（`data-width`/`data-height`），因此不适用于响应式断点。在制作 UI 预览时，你依然可以使用 `matchMedia` 来处理 `prefers-reduced-motion`，但这不会用于最终渲染输出的视频中。
+## 禁止事项
+- 在任何地方使用 `repeat: -1` —— 会破坏录制引擎。
+- 在 tween 值中使用 `Math.random()`、`Date.now()`、`performance.now()` —— 会导致非确定性。
+- 在 timeline 构建逻辑周围使用 `async` / `setTimeout` / `Promise` —— 录制引擎是以同步方式读取 `window.__timelines` 的。
+- 直接对 `visibility` 或 `display` 进行动画 —— 应改用 `autoAlpha`。
+- 对稍后才入场的 clip 元素使用 `gsap.set()` —— 它们在页面加载时还不存在于 DOM 中。请在 timeline 中使用 `tl.set(sel, vars, time)`。