hyperframes

HyperFrames

HTML 是视频的唯一可信来源。一个合成内容是一个 HTML 文件，其中包含用于计时的 data-* 属性、用于动画的 GSAP 时间线，以及用于外观的 CSS。该框架负责处理片段可见性、媒体播放和时间线同步。

OpenDesign 集成（对此流程至关重要）

当此技能在 OpenDesign 中运行时（即已设置 $OD_PROJECT_DIR）， 输出流程是固定的：只有渲染后的 .mp4 应出现在项目 根目录中。合成源文件（hyperframes.json、meta.json、 index.html、资源）应放在隐藏的缓存目录中，避免杂乱地出现在用户的 FileViewer 或聊天中的“已生成文件”标签里。

OD 内的渲染工作流——快速路径：

对于大多数 OD 请求（“测试视频”“5s 产品展示”“演示片段”）， 不要从头编写合成 HTML。使用 Open Design 的确定性脚手架，只修改提示词中实际要求变更的部分。“从头编写”路径需要耗费数分钟生成模型输出，并占用聊天工具时间；脚手架路径只需几秒。

# 1. Pick a hidden cache slot. Dotfile prefix → OD's project file
#    listing skips it, so the source files never clutter the chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"

# 2. Get an immediately-renderable scaffold (hyperframes.json,
#    meta.json, index.html with GSAP CDN + window.__timelines.main
#    already registered). Open Design writes these files itself; it does
#    not run `hyperframes init`, consult an npx cache, or install global skills.
"$OD_NODE_BIN" "$OD_BIN" media scaffold \
  --project "$OD_PROJECT_ID" \
  --composition-dir "$COMP_REL"

# 3. Edit ONLY $COMP/index.html — change `data-duration` on the root
#    if you need a non-default length, swap the placeholder palette
#    in <style>, add 1–3 clip <div>s for text/imagery, and append the
#    matching GSAP tweens inside the existing
#    `window.__timelines["main"] = gsap.timeline({paused:true})` block.
#    Keep edits minimal; the scaffold is already valid HF.

# 4. Dispatch render through the OD daemon. Do NOT run HyperFrames
#    `render` from this shell — the daemon runs it for you in an
#    unsandboxed process. (Many agent CLIs, Claude Code in particular,
#    wrap Bash in macOS sandbox-exec under which puppeteer's Chrome
#    subprocess hangs partway through frame capture. The daemon process
#    is unsandboxed, so renders complete reliably.)
#
#    The dispatcher returns within ~1s with a {taskId}; drive the
#    render to completion by looping `"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>` calls.
#    Each call long-polls up to 25s (well under your shell tool's
#    default 30s cap) and exits 0/2/5 to signal done/running/failed.
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
  --project "$OD_PROJECT_ID" \
  --surface video \
  --model hyperframes-html \
  --output "<descriptive-name>.mp4" \
  --composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
  out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
  ec=$?
  since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }

每次 generate 和每次 wait 调用最长约为 25s，因此 Agent shell 工具默认约 30s 的超时限制不会触发。整个循环期间，HF 的进度行（Capturing frame N/M）会实时流式输出到 stderr。 渲染完成后，stdout 的最后一行是 {"file": { "name": "<output>", "size": …, "kind": "video", … }} — 在回复中引用 file.name，让用户知道生成了什么。

在 OD 内跳过视觉风格关卡。 下方“方法”中的 HARD-GATE 部分 要求你在编写任何合成内容之前，先阅读 DESIGN.md / visual-style.md， 或者停下来询问 3 个风格问题。该关卡适用于独立的 HF 项目。OD 项目已有自己的设计系统层——用户在创建项目时已经选择了视觉方向。对于 OD 测试渲染，默认使用：深色画布（#0b0b0f）、一个暖色强调色（#ffb76b）、一个冷色强调色（#7da4ff），以及克制的动态效果。只有当用户的提示词含糊到无法确定主体时，才询问风格方面的意见（这种情况极少）。

何时跳过脚手架并从头编写：仅当用户明确要求空白模板显然无法承载的内容时（例如，多合成时间线、音频响应式叠加层、与用户已生成的 TTS 音轨同步的字幕）。其他情况一律默认采用初始化并编辑的路径。

你仍可直接在自己的 shell 中运行以下较轻量的 HF 子命令 （它们不需要启动 Chrome）：

• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" lint "$COMP" — 在分派前验证合成内容
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" transcribe <audio> — 生成字幕
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" tts <text> — 生成旁白

只有在运行 render/inspect/preview（任何需要 Chrome 的操作）时，才使用守护进程分派。在 .hyperframes-cache/ 下编写合成内容后，调用 "$OD_NODE_BIN" "$OD_BIN" media generate --surface video --model hyperframes-html --composition-dir <rel> 来渲染。守护进程会在你的 shell 沙箱之外运行需要 Chrome 的 HyperFrames 渲染，并将进度流式传回。不要自行运行 HyperFrames render。

不要将 hyperframes.json / meta.json / index.html 放在项目根目录中；OD 的文件列表会递归扫描，用户会看到聊天中多出三个无关文件。

对于 render 以外的 CLI 选项（lint、preview、transcribe、tts、inspect、 benchmark），请根据任务需要直接通过 shell 工具调用（例如，在合成内容中引用 TTS 音频之前，先将其生成到缓存目录中）。

方法

编写 HTML 之前，先从整体上进行思考：

1. 内容 — 观众应该体验到什么？明确叙事弧线、关键时刻和情绪起伏。
2. 结构 — 需要多少个画面组合？哪些是子组合，哪些是内联内容？各轨道承载什么内容（视频、音频、叠加层、字幕）？
3. 时长 — 哪些片段决定总时长？转场出现在哪里？节奏如何安排？
4. 布局 — 先构建最终状态。请参阅下文的“动画之前先完成布局”。
5. 添加动画 — 然后按照下方规则添加动态效果。

对于小幅修改（修复颜色、调整时间、添加一个元素），可直接从规则开始。

视觉风格检查关卡

编写任何画面组合 HTML 之前，必须先定义视觉风格。不要使用默认或通用配色来编写画面组合。

按以下顺序检查：

1. 项目中是否存在 DESIGN.md？ → 阅读该文件。严格使用其中指定的颜色、字体、动态效果规则和“What NOT to Do”约束。
2. 是否存在 visual-style.md？ → 阅读该文件。应用其中的 style_prompt_full 和结构化字段。（注意：visual-style.md 是项目专属文件。visual-styles.md 是包含 8 种命名预设的风格库，是不同的文件。）
3. 用户是否指定了风格（例如“Swiss Pulse”、“暗色科技感”、“奢华品牌”）？→ 阅读 visual-styles.md 中的 8 种命名预设。生成一个最简 DESIGN.md，包含：## Style Prompt（一个段落）、## Colors（3-5 个带用途说明的十六进制值）、## Typography（1-2 种字体系列）、## What NOT to Do（3-5 个反面模式）。
4. 以上都没有？ → 编写任何 HTML 之前先询问 3 个问题：
   • 想要什么氛围？（爆发力 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖）
   • 使用浅色还是深色画布？
   • 有没有指定的品牌颜色、字体或视觉参考？ 然后根据回答生成一个最简 DESIGN.md。

每个画面组合的配色和字体都必须能追溯到 DESIGN.md、visual-style.md 或用户的明确要求。如果你正打算使用 #333、#3b82f6 或 Roboto，说明你跳过了这一步。

对于动态效果默认设置、尺寸、入场模式和缓动，请遵循 house-style.md。house style 规定元素如何运动，DESIGN.md 规定元素是什么样子。

动画之前先完成布局

将每个元素放在其最醒目的时刻应处的位置——也就是元素已完全入场、位置正确但尚未开始退场的那一帧。先将其编写为静态 HTML+CSS。暂时不要使用 GSAP。

原因： 如果将元素放在动画的起始状态（画面外、缩放至 0、不透明度为 0），再通过补间动画将它们移动到你认为应该到达的位置，那就是在猜测最终布局。视频渲染出来之前，你无法看到元素之间的重叠。先构建最终状态，就能在添加动态效果之前查看并修复布局问题。

流程

1. 确定每个场景的主画面——也就是同时显示最多元素的时刻。布局以此为基础。
2. 为该画面编写静态 CSS。.scene-content 容器必须使用 width: 100%; height: 100%; padding: Npx;、display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 填满整个场景。使用内边距将内容向内推——绝不要在内容容器上使用 position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。仅将 position: absolute 用于装饰元素。
3. 使用 gsap.from() 添加入场效果——从画面外/不可见状态动画到 CSS 位置。CSS 位置是实际位置；补间动画描述的是元素如何到达该位置。
4. 使用 gsap.to() 添加退场效果——从 CSS 位置动画到画面外/不可见状态。

示例

/* scene-content fills the scene, padding positions content */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* Container fills any scene size (1920x1080, 1080x1920, etc).
   Padding positions content. Flex + gap handles spacing. */

错误 — 硬编码尺寸并使用绝对定位：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// Step 3: Animate INTO those positions
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Step 4: Animate OUT from those positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

当元素在不同时段共享同一区域时

如果元素 A 在元素 B 进入同一区域之前退出，那么两者在各自的片头帧中都应具有正确的 CSS 位置。时间线顺序可确保它们不会在视觉上同时出现，但如果跳过布局步骤，就无法发现它们因计时错误而意外重叠的情况。

什么情况属于有意重叠

分层效果（文字后方的辉光、阴影元素、背景图案）和按 z 轴堆叠的设计（卡片堆叠、深度图层）都属于有意设计。布局步骤旨在发现意外重叠，例如两个标题相互压叠、统计数据遮住标签，或内容溢出画面。

数据属性

所有片段

属性	必需	值
id	是	唯一标识符
data-start	是	秒数或片段 ID 引用（"el-1"、"intro + 2"）
data-duration	img/div/组合片段必需	秒数。视频/音频默认为媒体时长。
data-track-index	是	整数。同一轨道上的片段不能重叠。
data-media-start	否	源媒体中的修剪偏移量（秒）
data-volume	否	0-1（默认为 1）

data-track-index 不会影响视觉叠放顺序，请使用 CSS z-index。

组合片段

属性	必需	值
data-composition-id	是	唯一的组合 ID
data-start	是	开始时间（根组合：使用 "0"）
data-duration	是	优先于 GSAP 时间线时长
data-width / data-height	是	像素尺寸（1920x1080 或 1080x1920）
data-composition-src	否	外部 HTML 文件的路径

组合结构

通过 data-composition-src 加载的子组合使用 <template> 包装。独立组合（主 index.html）不使用 <template>，而是将 data-composition-id div 直接放在 <body> 中。在独立文件中使用 <template> 会让浏览器隐藏所有内容并导致渲染失败。

子组合结构：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根组合中加载：<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>

视频和音频

视频必须设置为 muted playsinline。音频始终使用单独的 <audio> 元素：

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

时间线约定

• 所有时间线均以 { paused: true } 开始，播放由播放器控制
• 注册每条时间线：window.__timelines["<composition-id>"] = tl
• 框架会自动嵌套子时间线，不要手动添加
• 时长取自 data-duration，而非 GSAP 时间线长度
• 切勿创建空补间来设置时长

规则（不可妥协）

确定性： 不要使用 Math.random()、Date.now() 或基于时间的逻辑。如果需要伪随机值，请使用带种子的 PRNG（例如 mulberry32）。

GSAP： 只动画视觉属性（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、transforms）。不要动画 visibility、display，也不要调用 video.play()/audio.play()。

动画冲突： 绝不要在多个时间轴上同时动画同一元素的同一属性。

不要使用 repeat: -1： 无限重复的时间轴会破坏捕获引擎。根据合成时长计算准确的重复次数：repeat: Math.ceil(duration / cycleDuration) - 1。

同步构建时间轴： 绝不要在 async/await、setTimeout 或 Promise 中构建时间轴。页面加载后，捕获引擎会同步读取 window.__timelines。编译器会嵌入字体，因此字体可立即使用，无需等待字体加载。

绝不要：

1. 忘记注册 window.__timelines
2. 用视频承载音频——始终使用静音视频 + 独立的 <audio>
3. 将视频嵌套在定时 div 中——使用非定时包装元素
4. 使用 data-layer（应使用 data-track-index）或 data-end（应使用 data-duration）
5. 动画视频元素的尺寸——改为动画包装 div
6. 对媒体调用 play/pause/seek——播放由框架控制
7. 创建没有 data-composition-id 的顶层容器
8. 在任何时间轴或补间中使用 repeat: -1——始终使用有限次数的重复
9. 异步构建时间轴（在 async、setTimeout、Promise 中）
10. 在后续场景的片段元素上使用 gsap.set()——页面加载时这些元素尚不存在于 DOM 中。应在时间轴内、片段的 data-start 时间点或之后使用 tl.set(selector, vars, timePosition)。
11. 在内容文本中使用 <br>——强制换行不会考虑实际渲染的字体宽度。自然换行的文本再加上 <br> 会导致多出不必要的换行，从而造成重叠。应使用 max-width 让文本自然换行。例外：每个词都刻意单独占一行的短展示标题（例如 130px 字号的 “THE\nIMMORTAL\nGAME”）。

场景转场（不可妥协）

每个多场景合成都必须遵循以下所有规则。违反任何一条都会导致合成损坏。

1. 始终在场景之间使用转场。 不要使用跳切。没有例外。
2. 始终为每个场景使用入场动画。 每个元素都必须通过 gsap.from() 动画进入。不得让元素以完整形态直接出现。如果场景有 5 个元素，就需要 5 个入场补间。
3. 绝不要使用退场动画，最终场景除外。这意味着：在转场开始前，禁止使用 gsap.to() 将 opacity 动画至 0、将 y 移出屏幕、将 scale 动画至 0，或使用任何其他“退出”动画。转场本身就是退场。转场开始时，离场场景的内容必须完全可见。
4. 仅限最终场景： 最后一个场景可以将元素淡出（例如淡至黑屏）。这是唯一允许使用 gsap.to(..., { opacity: 0 }) 的场景。

错误——转场前使用退场动画：

// BANNED — this empties the scene before the transition can use it
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// transition fires on empty frame

正确——仅使用入场动画，由转场处理退场：

// Scene 1 entrance animations
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NO exit tweens — transition at 7.2s handles the scene change
// Scene 2 entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

动画注意事项

• 首个动画延后 0.1-0.3s（不要设为 t=0）
• 让入场补间使用不同的缓动函数——每个场景至少使用 3 种不同的缓动函数
• 不要在同一场景中重复入场模式
• 深色背景避免使用全屏线性渐变（H.264 会产生色带——使用径向渐变，或纯色 + 局部光晕）
• 渲染视频中的标题字号至少为 60px，正文至少为 20px，数据标签至少为 16px
• 在数字列上使用 font-variant-numeric: tabular-nums

如果未提供 visual-style.md 或动画方向，请遵循 house-style.md 中的美学默认设置。

字体与素材

• 字体： 只需在 CSS 中写入所需的 font-family，编译器会自动嵌入受支持的字体。如果字体不受支持，编译器会发出警告。
• 为外部媒体添加 crossorigin="anonymous"
• 对于动态文本溢出，使用 window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })
• 所有文件都位于项目根目录，与 index.html 同级；子合成使用 ../

编辑现有合成

• 先通读整个合成——匹配现有字体、颜色和动画模式
• 只修改要求更改的内容
• 保留无关片段的时序

输出检查清单

• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" lint 和 "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" validate 均通过
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect 通过，或已为报告的每处溢出添加有意标记
• 已处理对比度警告（见下方“质量检查”）
• 已处理布局问题（见下方“质量检查”）
• 已验证动画编排（见下方“质量检查”）

质量检查

视觉检查

hyperframes inspect 会在无头 Chrome 中运行合成，遍历时间线，并标出视觉布局问题及其时间戳、选择器、边界框和修复提示。在 lint 和 validate 之后运行：

"$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect
"$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect --json

失败通常意味着文本溢出了气泡/卡片、固定尺寸标签裁切了动态文案，或文本移出了画布。可通过增大容器尺寸或内边距、减小字号或字间距、设置实际的 max-width 使文本在容器内换行，或对动态文案使用 window.__hyperframes.fitTextFontSize(...) 来修复。

对于内容密集的视频，使用 --samples 15；对于特定的主视觉帧，使用 --at 1.5,4,7.25。默认情况下会合并重复的静态问题，以免 Agent 上下文被大量信息淹没。如果溢出是入场/退场动画中有意为之，请为元素或其祖先添加 data-layout-allow-overflow 标记。如果装饰元素不应接受审计，请为其添加 data-layout-ignore 标记。

hyperframes layout 是同一检查的兼容别名。

对比度

默认情况下，hyperframes validate 会执行 WCAG 对比度审计。它会跳转到 5 个时间戳，为页面截图，采样每个文本元素背后的背景像素，并计算对比度。失败会以警告形式显示：

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

如果出现警告：

• 深色背景：提亮未通过的颜色，直到达到 4.5:1（普通文本）或 3:1（大号文本，24px 及以上，或粗体 19px 及以上）
• 浅色背景：调暗颜色
• 保持在同一色系中——不要另创颜色，调整现有颜色即可
• 重新运行 hyperframes validate，直到不再有警告

如果正在快速迭代且之后会检查，可使用 --no-contrast 跳过。

动画映射

编写动画后，运行动画映射以验证编排：

node design-templates/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

会输出一个 animation-map.json，其中包含：

• 每个补间动画的摘要："#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"
• ASCII 时间线：显示整个合成时长内所有补间动画的甘特图
• 错开检测：报告实际间隔（"3 elements stagger at 120ms"）
• 空白时段：超过 1s 且没有动画的时段——是有意停留，还是缺少入场动画？
• 元素生命周期：首次/最后动画时间、最终可见性
• 场景快照：5 个关键时间戳下可见元素的状态
• 标记：offscreen、collision、invisible、paced-fast（短于 0.2s）、paced-slow（长于 2s）

阅读 JSON。检查摘要中是否有异常内容。检查每个标记——修复或说明原因。确认时间线呈现了预期的编排节奏。修复后重新运行。

小幅编辑（修复颜色、调整单个时长）时可跳过。新建合成或对动画进行重大更改时应运行。

---

参考资料（按需加载）

• references/captions.md — 字幕、字幕文本、歌词、与音频同步的卡拉 OK。根据语气调整风格检测、逐词样式、文本溢出防止、字幕退出保障、词语分组。添加与音频时间同步的文本时阅读。

• references/tts.md — 使用 Kokoro-82M 进行文本转语音。语音选择、速度调节、TTS+字幕工作流。生成旁白或配音时阅读。

• references/audio-reactive.md — 音频响应动画：将频段和振幅映射到 GSAP 属性。视觉效果需要响应音乐、语音或声音时阅读。

• references/css-patterns.md — CSS+GSAP 标记高亮：高亮、圈选、爆发、涂鸦、勾画。确定性强，完全支持进度跳转。为文本添加视觉强调时阅读。

• references/typography.md — 排版：字体搭配、OpenType 特性、深色背景调整、字体发现脚本。务必阅读——每个作品都包含文本。

• references/motion-principles.md — 动态设计原则：缓动表达情绪、时长体现力度、编排构建层级、场景节奏、环境动态、反模式。编排 GSAP 动画时阅读。

• visual-styles.md — 8 种命名视觉风格（Swiss Pulse、Velvet Standard、Deconstructed、Maximalist Type、Data Drift、Soft Signal、Folk Frequency、Shadow Cut），包含十六进制调色板、GSAP 缓动特征和着色器搭配。用户指定风格或生成 DESIGN.md 时阅读。

• house-style.md — 未指定风格时采用的默认动态、尺寸和调色板。

• patterns.md — PiP、标题卡片、幻灯片模式。

• data-in-motion.md — 数据、统计信息和信息图模式。

• references/transcript-guide.md — 转录命令、whisper 模型、外部 API、故障排除。

• references/dynamic-techniques.md — 动态字幕动画技巧（卡拉 OK、clip-path、slam、scatter、elastic、3D）。

• references/transitions.md — 场景转场：交叉淡化、擦除、揭示、着色器转场。能量/情绪选择、CSS 与 WebGL 指引。多场景作品务必阅读——没有转场的场景看起来就像硬切。

  • transitions/catalog.md — 硬性规则、场景模板，以及按类型查找实现代码的指引。
  • 着色器转场位于 @hyperframes/shader-transitions（packages/shader-transitions/）中——请阅读软件包源代码，而不是技能文件。

• references/html-in-canvas.md — HTML-in-Canvas（drawElementImage），用于将实时 DOM 渲染为 WebGL 纹理：3D 设备模型、着色器扭曲 UI、液态玻璃、传送门。用户要求使用 vfx-iphone-device、vfx-liquid-glass、vfx-portal 或任何“将 HTML 映射到 3D/着色器”的效果时阅读。渲染路径会自动启用 Chrome 标志，但动画内容必须每帧重新捕获纹理——这是导致“屏幕渲染后没有动效”这一输出的最常见原因。

GSAP 模式和效果位于 /gsap 技能中。