# HyperFrames AI Generation Patterns 生成日期: 2026-06-29 来源: HyperFrames 官方 registry `https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry`。本文件基于 133 个可读取 block/component 的 `registry-item.json` 与 132 个源码文件扫描总结，目标是帮助未来用 AI 生成更好看、可渲染、符合 HyperFrames 框架规范的转场、组件和动效。 ## 1. 核心结论 - 绝大多数可动画条目使用 `gsap.timeline({ paused: true })`，并注册到 `window.__timelines[compositionId]`。 - 完整 block 是独立 HTML composition，根节点通常带 `data-composition-id`、`data-width`、`data-height`、`data-start`、`data-duration`。 - 可叠加/可复用 component 通常是 snippet，不一定是完整 HTML；应可 paste 到现有 composition 中。 - 可渲染性优先级高于“炫技”。AI 生成时必须保证 deterministic timeline、固定画布、无交互阻塞、资源加载完成后才注册 timeline。 - 最稳定的视觉模式是“清晰分层 + scoped CSS + GSAP 驱动状态变化 + 最后一帧 padding 到完整 duration”。 - 高级 VFX/WebGL/3D 可以做，但必须提供 fallback 或延迟注册策略，否则 preview/render 容易空白。 ## 2. 扫描统计证据源码扫描结果: - 源码文件: 132 个 - `gsap.` 出现文件: 124 个 - `gsap.timeline` 出现文件: 124 个 - `window.__timelines` 出现文件: 124 个 - `data-start` 出现文件: 99 个 - `data-duration` 出现文件: 101 个 - `data-track-index` 出现文件: 63 个 - SVG/filter/mask 相关出现文件: 97 个 - canvas 相关出现文件: 45 个 - WebGL/shader/Three 相关出现文件: 29 个 - caption/word/karaoke 相关出现文件: 35 个 - CSS 变量定义出现文件: 23 个 - `document.fonts.ready` 出现文件: 9 个 - 仅 CSS keyframes 作为主动画的文件很少，代表是 `grain-overlay`。读取异常: - `code-morph` 的 manifest 拉取失败。 - `swirl-vortex.html` 源码拉取失败，但 registry item 可读取。 ## 3. Block vs Component 生成准则 ### 3.1 生成 Block 的场景生成完整 block，当它是一个完整镜头、独立段落或可通过 `data-composition-src` 嵌入的 composition。适合: - 一段 5-15 秒的完整开场、结尾、数据图、地图、代码演示、产品展示。 - 需要独立 width/height/duration 的场景。 - 需要 preview poster/video 的 registry 条目。 - 转场 showcase 或单个 shader transition demo。 Block 最小结构: ```html

``` ### 3.2 生成 Component 的场景生成 component，当它应该被 paste 到另一个 composition，而不是独立成片。适合: - 质感覆盖层: grain、vignette、shimmer。 - 可复用效果函数: motion blur、texture mask、morph text。 - 字幕样式: caption-*。 - 转场 helper: parallax zoom/unzoom、grid pixelate wipe。 Component 最小结构: ```html ``` ## 4. Timeline 注册范式 ### 4.1 标准同步注册适合无需等待字体、图片、GLTF、WebGL 编译的普通动效。 ```js window.__timelines = window.__timelines || {}; var tl = gsap.timeline({ paused: true }); gsap.set(".card", { opacity: 0, y: 24 }); tl.to(".card", { opacity: 1, y: 0, duration: 0.55, ease: "power3.out" }, 0.2); tl.to(".card", { opacity: 0, y: 18, duration: 0.35, ease: "power2.in" }, 4.3); tl.set(".card", { visibility: "hidden" }, 4.75); window.__timelines["my-id"] = tl; ``` 来自: lower-third 系列、社媒卡片、通知卡片。 ### 4.2 等字体后注册适合代码排版、逐字输入、需要 `getBoundingClientRect()` 或 canvas text measurement 的效果。关键点是: 不要先注册空 timeline，否则作为 sub-composition 时 runtime 可能把空 timeline 嵌进去，后续不会重绑。 ```js function go() { var root = document.getElementById("root"); var tl = gsap.timeline({ paused: true }); document.fonts.ready.then(function () { buildLayoutAndTweens(tl); var dur = parseFloat(root.dataset.duration) || tl.duration(); tl.to({}, { duration: dur }, 0); window.__timelines = window.__timelines || {}; window.__timelines["my-code-block"] = tl; if (typeof window.__hfForceTimelineRebind === "function") { window.__hfForceTimelineRebind(); } }); } if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", go); else go(); ``` 来自: `code-typing`、`code-highlight`、`code-scroll`。 ### 4.3 等资源后注册适合 GLTF/3D、外部纹理、截图到 canvas 的设备展示。关键点是所有关键资源 ready 以后再注册 timeline。 ```js var tl = gsap.timeline({ paused: true }); tl.to(state, { p: 1, duration: DURATION, ease: "none", onUpdate: render }, 0); function onReady() { requestAnimationFrame(function () { requestAnimationFrame(function () { captureScreens(); window.__timelines = window.__timelines || {}; window.__timelines["devices-canvas"] = tl; }); }); } ``` 来自: `vfx-iphone-device`。 ### 4.4 WebGL fallback 注册适合 shader 转场、WebGL VFX。关键点是 `gl` 不可用时也必须注册一个 paused timeline，避免 renderer 挂住。 ```js window.__timelines = window.__timelines || {}; var gl = canvas.getContext("webgl", { preserveDrawingBuffer: true }); if (!gl) { console.warn("WebGL not available"); window.__timelines["main"] = gsap.timeline({ paused: true }); } else { var tl = gsap.timeline({ paused: true, onUpdate: function () { renderShader(tl.time()); }, }); tl.to({ v: 0 }, { v: 1, duration: DURATION, ease: "none" }, 0); window.__timelines["main"] = tl; } ``` 来自: shader transition 系列、`vfx-text-cursor`。 ## 5. Visual Quality Patterns ### 5.1 好看的 composition 通常有 4 层推荐分层: 1. Atmosphere: 背景渐变、网格、光晕、噪声、地图底图或柔和 vignette。 2. Subject: 主要卡片、设备、文字、图表、代码窗口。 3. Motion Accent: 扫光、粒子、描边、cursor、connector、line draw、mask reveal。 4. Focus/Finish: 下三分之一、标签、source note、logo、CTA、exit fade。生成时不要只画一个居中白卡。至少给背景、主元素、动效重点各一个明确设计决策。 ### 5.2 最常见的入场/出场组合稳定组合: - `clip-path: inset(...)` 做横向/纵向 wipe。 - `opacity + y` 做文字上升。 - `scale + blur` 做卡片/设备柔和入场。 - `drawSVG` 类效果可用 SVG path dasharray/dashoffset 替代插件。 - 退出时不要只 opacity 0，最好加轻微 y/scale/blur，最后 `visibility: hidden`。示例: ```js gsap.set(card, { clipPath: "inset(0 100% 0 0)" }); gsap.set(title, { y: 22, opacity: 0 }); tl.to(card, { clipPath: "inset(0 0% 0 0)", duration: 0.55, ease: "power3.out" }, 0.1); tl.to(title, { y: 0, opacity: 1, duration: 0.5, ease: "power3.out" }, 0.34); tl.to(card, { y: 18, opacity: 0, duration: 0.35, ease: "power2.in" }, DURATION - 0.5); tl.set(card, { visibility: "hidden" }, DURATION - 0.05); ``` ### 5.3 CSS scoping Block 内 CSS 应用 `[data-composition-id="..."]` scope，避免作为 sub-composition 或 snippet 时污染外部。 ```css [data-composition-id="data-chart"] .headline { ... } [data-composition-id="data-chart"] .bar { ... } ``` Component 应使用唯一 id 或 `hf-` 前缀类名。 ```css #grain-overlay .grain-texture { ... } .hf-caption-highlight .caption-word { ... } ``` ### 5.4 CSS 变量接口当效果需要可调色彩/强度，优先暴露 CSS custom properties。VS Code theme 和 liquid glass 系列大量使用这一范式。 ```css [data-composition-id="my-card"] { --accent: #ff5a36; --surface: #ffffff; --text: #0f1115; --shadow-opacity: 0.18; } ``` 生成 registry item 时可把重要变量写入 `params`，例如 `--bg-color`、`--text-color`。 ## 6. 转场生成范式 ### 6.1 普通 HTML/CSS 转场适合 cover、push、blur、radial、scale、grid。结构上放两个 scene，再用 mask/clip/transform 过渡。 ```html

...

``` ```js gsap.set(sceneB, { opacity: 0, scale: 1.04 }); tl.to(sceneA, { scale: 0.97, filter: "blur(8px)", duration: 1.1, ease: "power2.inOut" }, 1.2); tl.to(sceneB, { opacity: 1, scale: 1, duration: 1.1, ease: "power2.inOut" }, 1.2); ``` ### 6.2 Shader 转场代表条目: `domain-warp-dissolve`、`ridged-burn`、`whip-pan`、`sdf-iris`、`ripple-waves`、`gravitational-lens`、`cinematic-zoom`、`chromatic-radial-split`、`glitch`、`thermal-distortion`、`flash-through-white`、`cross-warp-morph`、`light-leak`。范式: - 用 DOM scene 先构建 from/to。 - 用 canvas 捕获 scene 到 texture。 - fragment shader 接收 `u_from`、`u_to`、`u_progress`、`u_resolution`。 - timeline `onUpdate` 用 `tl.time()` 转为 progress。 - WebGL 不可用时注册空 timeline 或 fallback DOM fade。 AI 生成 shader 时应控制复杂度: - 必须有 deterministic noise，不要依赖实时随机。 - `u_progress` 必须 clamp 到 `[0,1]`。 - shader 编译失败要 `console.error`，不要 throw 到阻断注册。 - fragment shader 字符串要保持短且可读，避免生成超大不可维护代码。 ### 6.3 转场不要做的事 - 不要用 `setInterval` 或无限 `requestAnimationFrame` 驱动主进度；应该让 HyperFrames seek timeline。 - 不要把进度绑定到 wall-clock `Date.now()`。 - 不要假设用户交互或 hover。 - 不要在 render frame 中创建大量 DOM/texture。 ## 7. Component 生成范式 ### 7.1 Overlay component 代表: `grain-overlay`、`vignette`。特点: - 无需 GSAP timeline。 - absolute full viewport。 - `pointer-events: none`。 - z-index 可调。 - 可用 CSS keyframes，但要简短、steps 或 deterministic。 ```html ``` ### 7.2 Timeline-attached component 代表: `motion-blur`。特点: - 提供 `attachX(selector, tl, options)`。 - 调用时机写清楚: 在所有 tween 定义后、`window.__timelines` 注册前。 - 如果需要 per-frame update，不依赖 `tl.eventCallback("onUpdate")`；可添加一个 duration driver tween，用 tween `onUpdate` 适配 HyperFrames renderer 的 seek。 ```js var proxy = { t: 0 }; tl.to(proxy, { t: 1, duration: Math.max(tl.duration(), 0.1), ease: "none", onUpdate: function () { // read gsap.getProperty(target, "x") / "y" and update effect } }, 0); ``` ### 7.3 Text effect component 代表: `shimmer-sweep`、`texture-mask-text`、`morph-text`、`caption-blend-difference`。生成建议: - 支持传 selector 或写明需要包裹的 DOM。 - 使用 mask/filter/blend-mode 时提供 fallback color。 - 文字效果应支持短文本和多词文本，避免只适配单个 demo 单词。 - 使用 SVG filter 时，id 要唯一，避免多个实例冲突。 ## 8. Caption 生成范式代表: `caption-pill-karaoke`、`caption-neon-accent`、`caption-weight-shift`、`caption-emoji-pop`、`caption-editorial-emphasis`、`caption-parallax-layers`、`caption-glitch-rgb`、`caption-matrix-decode`、`caption-particle-burst`、`caption-texture`、`caption-clip-wipe`、`caption-kinetic-slam`、`caption-gradient-fill`、`caption-neon-glow`、`caption-highlight`。 ### 8.1 Caption 数据结构推荐接受 word-level transcript: ```js var TRANSCRIPT = [ { text: "Every", start: 0.0, end: 0.3 }, { text: "great", start: 0.3, end: 0.55 }, { text: "video", start: 0.55, end: 0.85 } ]; ``` Normalize: ```js function normalizeWords(rawWords) { return rawWords.map(function (item) { var text = String(item.word || item.text || "").trim(); return { text: text, start: Math.max(0, Number(item.start) || 0), end: Math.max(Number(item.start) || 0, Number(item.end) || 0) }; }).filter(function (w) { return w.text.length > 0; }); } ``` ### 8.2 Caption 分组策略源码中常见策略: - 按 `MAX_WORDS_PER_GROUP` 控制每组词数。 - 遇到标点、自然停顿、下一组太宽时断组。 - 使用 canvas measureText 估算宽度。 - 字体过宽时从 base font size 逐步降到 min font size。 - 每组可见时间从第一个词 start 到最后词 end，并加 buffer。 AI 生成字幕组件时必须处理: - 长词。 - 两行布局。 - 口播停顿。 - 最后一组持续到 duration 结束。 - active word 与 inactive word 的区别。 ### 8.3 Caption timeline ```js window.__timelines = window.__timelines || {}; var tl = gsap.timeline({ paused: true }); GROUPS.forEach(function (group, groupIndex) { var groupEl = document.getElementById("caption-group-" + groupIndex); var visibleStart = Math.max(0, group.start); var visibleEnd = Math.min(DURATION, group.end + 0.3); tl.set(groupEl, { opacity: 1 }, visibleStart); tl.set(groupEl, { opacity: 0 }, visibleEnd); group.words.forEach(function (word, wordIndex) { var wordEl = document.getElementById("caption-word-" + groupIndex + "-" + wordIndex); tl.to(wordEl, { color: ACTIVE, duration: 0.1, ease: "none" }, word.start - 0.05); }); }); window.__timelines["caption-style-id"] = tl; ``` ### 8.4 Caption visual quality rules - 短视频风格: high contrast, big type, clear active word. - Editorial 风格: dual-font, size contrast, restrained color. - Gaming/cyber 风格: glow, RGB split, scanline, but keep readability. - Parallax/3D 风格: use depth sparingly; do not obscure face/safe zone. - Always keep safe zone, usually bottom center, width around 1400-1600 px for 1920x1080. ## 9. Code/Terminal 生成范式 ### 9.1 Terminal blocks 代表: Apple Terminal profiles。范式: - 固定 terminal window chrome。 - `COMMANDS` 或 lines array 作为数据。 - per-character typing。 - Cursor blink/position 由 timeline 控制，不能依赖 real-time CSS animation。 - 主题差异通过 colors/font/background 配置，而不是复制大量逻辑。 ### 9.2 VS Code blocks 代表: `code-snippet-*`。范式: - Workbench chrome: titlebar, activity bar, sidebar, tabs, editor, terminal, statusbar。 - Theme tokens 映射到 CSS variables。 - Code tokens 是结构化数组 `{ text, token }`。 - `renderCode(root)` 生成 line/token spans。 - `buildTimeline(root, compositionId)` 处理 typing/caret/highlight。推荐数据结构: ```js var CODE_LINES = [ [{ text: "function", token: "keyword" }, { text: " build", token: "function" }], [{ text: " return", token: "keyword" }, { text: " frame", token: "variable" }] ]; ``` ### 9.3 代码演示质量规则 - 使用等宽字体，不要默认 system monospace；优先 JetBrains Mono、SF Mono、IBM Plex Mono 等。 - 字号应可读，1080p 建议 26-34px。 - 不要一次展示太多代码；聚焦 6-14 行。 - 加 active line/highlight/caret，帮助观众知道该看哪里。 - 如果使用 `getBoundingClientRect()` 定位 caret/highlight，必须等 `document.fonts.ready`。 ## 10. Data / Map / Diagram 范式代表: `data-chart`、`us-map`、`world-map`、`flowchart`。 ### 10.1 数据图范式: - 数据 array 写在 script 顶部。 - SVG 动态创建 gridlines/bars/labels/paths。 - 使用 scale 函数计算位置。 - 入场顺序: headline wipe -> legend fade -> gridline fade -> bars stagger -> line draw -> labels fade。 - source note 最后淡入。 ```js var tl = gsap.timeline({ paused: true }); tl.to(".headline", { clipPath: "inset(0 0% 0 0)", duration: 0.7 }, 0.2); tl.to(".grid-line", { opacity: 1, stagger: 0.05, duration: 0.4 }, 0.8); tl.fromTo(".bar", { scaleY: 0 }, { scaleY: 1, transformOrigin: "bottom", stagger: 0.12, duration: 0.8 }, 1.1); tl.to(".conversion-path", { strokeDashoffset: 0, duration: 1.2 }, 2.0); ``` ### 10.2 地图范式: - 地图最好用 SVG path，不依赖 remote map tiles。 - Choropleth 使用 fill scale + stagger reveal。 - Flow/bubble map 使用 arc/path/circle + labels。 - 地理解释类 YouTube insert 可配合 marker、scribble circle、callout label、editorial wash。 ### 10.3 Flowchart 范式: - Node 是普通 DOM 卡片。 - Connector 是 SVG path/line。 - Timeline 先入场 node，再 draw connector，再 cursor/typing correction。 - Portrait variant 应单独设计，不要只 scale 16:9。 ## 11. 3D / WebGL / HTML-in-Canvas 范式 ### 11.1 HTML-in-Canvas / drawElementImage 代表: `vfx-iphone-device`、liquid glass 系列。范式: - DOM 写出真实 UI。 - Canvas/Three 获取 DOM 纹理或截屏。 - 动画状态对象 `S` 驱动 camera/device/UI values。 - Timeline tween `S`，`onUpdate: render`。 - 资源 ready 后捕获屏幕并注册 timeline。 ### 11.2 Liquid Glass 代表: `liquid-glass-context-menu`、`liquid-glass-notification`、`liquid-glass-media-controls`。范式: - 大量 CSS variables 描述材质: blur、refraction、corner radius、specular、fresnel、chrom aberration、tint、brightness、saturation。 - 一个背景 canvas 或 Three shader。 - 一个 glass canvas 或 layout subtree 承载玻璃面板。 - Timeline 既驱动 DOM 位置，也触发 `requestGlassRender(tl.time())`。 ### 11.3 3D 设备展示范式: - GLTF model load 后才 register timeline。 - 设备运动拆成 acts: hero close-up, spin, exit, second device enter, turntable。 - Camera values、device transforms、screen scroll/counter/card reveal 用同一个 state object。 - Render loop必须由 timeline seek 驱动，避免 real-time drift。 ## 12. Registry Item 生成建议 Block registry item: ```json { "$schema": "https://hyperframes.heygen.com/schema/registry-item.json", "name": "my-transition", "type": "hyperframes:block", "title": "My Transition", "description": "A concise description of the visual effect", "tags": ["transition", "shader"], "dimensions": { "width": 1920, "height": 1080 }, "duration": 4, "files": [ { "path": "my-transition.html", "target": "compositions/my-transition.html", "type": "hyperframes:composition" } ], "params": [ { "key": "--accent", "label": "Accent", "type": "color", "default": "#58a6ff" } ] } ``` Component registry item: ```json { "name": "my-overlay", "type": "hyperframes:component", "title": "My Overlay", "description": "A reusable overlay component", "tags": ["overlay", "effect"], "files": [ { "path": "my-overlay.html", "target": "compositions/components/my-overlay.html", "type": "hyperframes:snippet" } ] } ``` ## 13. AI Prompt Checklist When asking AI to generate a HyperFrames effect, include: - Output type: block or component. - Canvas: `1920x1080` or portrait dimensions. - Duration: exact seconds. - Visual direction: typography, color palette, mood, references. - Data/content: transcript, code lines, map values, labels, social post content. - Runtime constraints: use GSAP timeline, paused, register to `window.__timelines[id]`. - Resource constraints: inline SVG/CSS preferred; external assets only if registry will include them. - Fallback needs: WebGL/Three/GLTF fallback or delayed timeline registration. - Integration: for component, explain paste location and any `attachX()` call. Reusable prompt skeleton: ```text Generate a HyperFrames [block/component] named [id]. It must render at [width]x[height], duration [seconds]s. Use a paused GSAP timeline and register it as window.__timelines["[id]"]. Use scoped CSS under [data-composition-id="[id]"] or a unique component id. Avoid wall-clock time, hover, user interaction, and unbounded requestAnimationFrame loops. If measuring text, wait for document.fonts.ready before registering the timeline. If using WebGL/Three/assets, register only after resources are ready and provide a safe fallback. Visual direction: [specific mood, typography, palette, layout]. Content/data: [specific content]. Return complete HTML and, if registry-ready, include registry-item.json. ``` ## 14. Anti-Patterns To Avoid - Registering `window.__timelines[id]` before the timeline is populated when async setup is required. - Relying on CSS animations for primary timing when the renderer seeks the GSAP timeline. - Using `Date.now()` or real-time RAF to determine animation progress. - Missing `data-duration`, `data-width`, `data-height`, or timeline padding. - Global CSS selectors that pollute the host composition. - Non-unique SVG filter ids in reusable components. - Huge unscoped external dependencies when vanilla SVG/CSS/GSAP is enough. - Visual center-only layouts with no atmosphere, no accent motion, no hierarchy. - Text too small for video or contrast too low for captions. - WebGL code that throws before registering fallback timeline. ## 15. Category-Specific Generation Recipes ### Lower Third Use when: interviews, podcasts, expert intro, news overlays. Recipe: - Transparent body. - Position at lower left, inside safe margins. - One accent element: tab, underline, side rule, or role bar. - Name large and high contrast; role smaller and muted. - Entry: card wipe + accent grow + text rise. - Exit: y/opacity out + visibility hidden. ### Social Card Overlay Use when: X/Reddit/Spotify/YouTube/notification inserts. Recipe: - Card with platform-specific chrome. - Avatar/icon, account, content, metrics/status. - Entry: scale-pop or slide from edge. - Inner stagger: avatar -> text -> metrics -> CTA. - Keep `pointer-events: none` if overlay component. ### Caption Style Use when: talking-head short-form video. Recipe: - Word-level transcript. - Group into 2-4 words, split into max 2 lines. - Safe zone bottom center. - Timeline controls group visibility and active word. - Prioritize readability over decorative effects. ### Shader Transition Use when: premium scene change. Recipe: - Two DOM scenes. - Capture to textures. - Fragment shader blends with `u_progress`. - Timeline `onUpdate` renders progress. - WebGL fallback registers timeline. ### Code Demo Use when: developer product, AI coding tool, tutorial. Recipe: - Editor or terminal chrome. - Structured code tokens or command lines. - Wait for fonts before metrics. - Typing/caret/highlight line tell the story. - Use theme CSS variables for reuse. ### Product/Device 3D Use when: app launches, device UI showcase. Recipe: - DOM UI captured as texture. - GLTF or CSS 3D device. - State object drives camera, transforms, screen content. - Wait for assets; register timeline only when ready. - Acts-based choreography, not random spinning. ## 16. Fast Quality Rubric Before accepting AI-generated HyperFrames code, check: - Does it register a paused timeline with the correct id? - Does the timeline cover the declared duration? - Is the visual scope fixed to the declared dimensions? - Are all CSS selectors scoped or unique? - Are async resources handled before registration? - Does it avoid wall-clock timing and user interaction? - Is there at least one clear visual hierarchy: title/subject/accent/background? - Is text readable at final video size? - Does it have an exit or stable hold state? - For components, is usage documented and paste-safe? ## 17. Representative Source Patterns - `lt-clean-bar`: compact lower-third block, clean example of clip-path wipe, accent tab, text stagger, exit hide. - `caption-pill-karaoke`: robust transcript normalization, group planning, width measurement, word highlight timeline. - `motion-blur`: reusable component API, attaches to caller timeline, uses SVG filters, avoids timeline event callback pitfalls. - `domain-warp-dissolve`: DOM scene capture to WebGL textures, shader progress controlled by timeline, fallback registration. - `code-typing`: waits for `document.fonts.ready`, registers after populated, uses force rebind hook. - `vfx-iphone-device`: waits for GLTF and double RAF before registering timeline, state-object render model. - `grain-overlay`: pure CSS paste-safe overlay with `pointer-events: none` and deterministic grain keyframes. ## 18. Recommended Next Step If this guide becomes an internal generation standard, turn sections 3-16 into a reusable Codex skill or prompt pack: - `hyperframes-block-template` - `hyperframes-component-template` - `hyperframes-transition-template` - `hyperframes-caption-template` - `hyperframes-quality-review` That would let future generation tasks start from these validated patterns rather than rediscovering framework rules each time.