npm - hyper-animator-codex - Versions diffs - 0.7.1 → 0.8.1 - Mend

hyper-animator-codex 0.7.1 → 0.8.1

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 (321) hide show

package/skills/hyper-animator-codex/references/HyperFrames-AI-Generation-Patterns-codex.md ADDED Viewed

@@ -0,0 +1,788 @@
+# 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
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <script src="https://cdn.jsdmirror.com/npm/gsap@3.15/dist/gsap.min.js"></script>
+    <script>
+    if (typeof gsap === 'undefined') {
+      document.write('<script src="https://cdn.jsdmirror.cn/npm/gsap@3.15/dist/gsap.min.js"><\/script>');
+    }
+    </script>
+    <script>
+    if (typeof gsap === 'undefined') {
+      document.write('<script src="https://s4.zstatic.net/npm/gsap@3.15/dist/gsap.min.js"><\/script>');
+    }
+    </script>
+    <style>
+      * { box-sizing: border-box; }
+      html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; }
+      [data-composition-id="my-block"] { position: relative; width: 1920px; height: 1080px; overflow: hidden; }
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="my-block" data-start="0" data-duration="8" data-width="1920" data-height="1080">
+      <div class="clip" data-start="0" data-duration="8" data-track-index="0">
+        <!-- visual layers -->
+      </div>
+    </div>
+    <script>
+      (function () {
+        window.__timelines = window.__timelines || {};
+        var tl = gsap.timeline({ paused: true });
+        // set initial states
+        // add tweens
+        tl.to({}, { duration: 8 }, 0); // pad to full duration
+        window.__timelines["my-block"] = tl;
+      })();
+    </script>
+  </body>
+</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
+<!--
+  Component Name - short description.
+  Usage:
+  Paste this snippet into a HyperFrames composition.
+  If it needs a timeline, call its attach/build function after creating the main tl and before window.__timelines registration.
+-->
+<div id="my-component" class="hf-my-component" aria-hidden="true"></div>
+<style>
+  #my-component { position: absolute; inset: 0; pointer-events: none; z-index: 100; }
+</style>
+<script>
+  (function () {
+    window.attachMyComponent = function (tl, options) {
+      options = options || {};
+      // attach tweens or runtime effect to the caller timeline
+    };
+  })();
+</script>
+```
+## 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
+<div id="root" data-composition-id="main" data-duration="4" data-width="1920" data-height="1080">
+  <section id="scene-a" class="scene">...</section>
+  <section id="scene-b" class="scene">...</section>
+  <div class="transition-mask"></div>
+</div>
+```
+```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
+<div id="hf-vignette" aria-hidden="true"></div>
+<style>
+  #hf-vignette {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 90;
+    background: radial-gradient(circle at center, transparent 50%, rgba(0,0,0,.34) 100%);
+  }
+</style>
+```
+### 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.