zcode hf-extract：MP4/GIF/WebP 媒体提取（前文已述）

zcode hf-gen：CSS 动画生成（前文已述）

zcode hf-sprite：雪碧图生成（前文已述）

zcode hf-build：终极打包命令
它不是简单合并文件，而是执行智能注入：

• 读取 HTML 中所有>zcode hf-build --input ./src/index.html \ --output ./dist/ \ --watch # 开发时实时监听

  --watch模式下，你改一个 MP4，CLI 自动重跑整个链路，5 秒后浏览器刷新，新帧序列已就绪。这才是 hyperframes 的效率本质：把媒体资产当作代码一样管理，变更即生效。

  4. 实操全流程：从零开始构建一个“涟漪光圈扩散”按钮（适配 1440x810 容器）

  4.1 需求确认与设计输入：对齐设计师的 AE 时间轴

  热搜词里有css涟漪光圈扩散和宽1440px,高810px，这是一个明确的设计约束。我们拿到的设计师交付物，是一个 After Effects 工程，导出为 MP4，但更重要的是 AE 的“关键帧信息”导出为 JSON：

  // ripple_design.json { "name": "ripple-circle", "canvas": { "width": 1440, "height": 810 }, "layers": [ { "id": "circle", "type": "shape", "properties": [ { "time": 0, "scale": [0,0], "opacity": 100 }, { "time": 0.3, "scale": [250,250], "opacity": 0 } ] } ] }

  注意time单位是秒，scale是百分比。这个 JSON 就是zcode hf-gen的输入源。我们不需要 AE，只需要这个 JSON 描述的动画逻辑。

  4.2 CLI 生成 CSS 帧序列：命令与输出分析

  执行命令：

  zcode hf-gen \ --input ./design/ripple_design.json \ --output ./dist/css/ripple.css \ --fps 60 \ --duration 300 \ --canvas-width 1440 \ --canvas-height 810

  --duration 300是毫秒（0.3 秒），--fps 60生成 18 帧（300ms ÷ 16.67ms ≈ 18）。CLI 输出关键日志：

  [INFO] Loaded design from ./design/ripple_design.json [INFO] Canvas size: 1440x810 (matches target) [INFO] Generating 18 frames at 60fps... [INFO] Interpolating 'scale' with cubic-bezier(0.25,0.46,0.45,0.94) [INFO] Writing CSS to ./dist/css/ripple.css (size: 4.2KB)

  生成的ripple.css核心内容：

  .hf-ripple { position: relative; overflow: hidden; } .hf-ripple::before { content: ''; position: absolute; top: 0; left: 0; width: 100%; height: 100%; background: radial-gradient(circle, rgba(255,255,255,0.8) 0%, rgba(255,255,255,0) 70%); transform: scale(0); opacity: 0; transition: transform 0.3s cubic-bezier(0.25,0.46,0.45,0.94), opacity 0.3s cubic-bezier(0.25,0.46,0.45,0.94); } .hf-ripple[data-hf-ripple="0"]::before { transform: scale(0); opacity: 0.8; } .hf-ripple[data-hf-ripple="1"]::before { transform: scale(0.12); opacity: 0.75; } .hf-ripple[data-hf-ripple="2"]::before { transform: scale(0.24); opacity: 0.7; } /* ... 直到 frame 17 */ .hf-ripple[data-hf-ripple="17"]::before { transform: scale(2.5); opacity: 0; }

  注意：这里没用@keyframes，而是用><!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=1440, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> <title>Hyperframes 涟漪按钮</title> <link rel="stylesheet" href="./dist/css/ripple.css"> <style> /* 重置 body，确保无滚动条、无边距 */ body { margin: 0; padding: 0; width: 1440px; height: 810px; overflow: hidden; background: #1a1a1a; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto; } .container { width: 1440px; height: 810px; display: flex; justify-content: center; align-items: center; } </style> </head> <body> <div class="container"> <button class="hf-ripple">.hf-ripple { --origin-x: 50%; --origin-y: 50%; } .hf-ripple::before { transform-origin: var(--origin-x) var(--origin-y); }

  JS 中：

  btn.addEventListener('click', function(e) { const rect = btn.getBoundingClientRect(); const x = e.clientX - rect.left; const y = e.clientY - rect.top; // 转换为百分比 const originX = (x / rect.width * 100) + '%'; const originY = (y / rect.height * 100) + '%'; btn.style.setProperty('--origin-x', originX); btn.style.setProperty('--origin-y', originY); // 后续帧切换逻辑... });

  实操心得：transform-origin的百分比值，必须是字符串加%，不能是数字。我曾因写btn.style.setProperty('--origin-x', x)导致涟漪消失，调试 2 小时才发现是类型错误。

  5.2 “MP4 提取失败：No such file or directory”：FFmpeg 路径与权限的魔鬼细节

  zcode hf-extract依赖系统 FFmpeg。在 Ubuntu 上，sudo apt install ffmpeg安装的版本常是 4.x，而 CLI 需要 5.1+ 的libavcodecAPI。错误日志只显示No such file or directory，实际是动态链接库版本不匹配。

  解决方案：

  1. 下载静态编译版 FFmpeg：wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-git-amd64-static.tar.xz
  2. 解压后，sudo cp ffmpeg-git-*/ffmpeg /usr/local/bin/ffmpeg-static
  3. 修改zcode配置，指定ffmpegPath: '/usr/local/bin/ffmpeg-static'

  注意：不要用snap install ffmpeg，snap 的沙盒机制会阻止 CLI 访问临时文件目录，导致提取失败。这是 Ubuntu 用户的高频坑。

  5.3 “雪碧图显示错位”：PNG 元数据中的 DPI 陷阱

  现象：雪碧图在 Chrome 正常，但在 Safari 显示偏移 1px。根源是 PNG 文件嵌入的 DPI 元数据（如 72dpi vs 96dpi），Safari 会据此缩放图像。

  解决方案：用pngcrush清理元数据：

  find ./frames/ -name "*.png" -exec pngcrush -rem alla {} {}_clean \; mv ./frames/*_clean ./frames/

  -rem alla移除所有 ancillary chunks（包括 DPI）。CLI 工具zcode hf-sprite内部已集成此步骤，但如果你手动处理 PNG，务必执行。

  5.4 “data-hf-frame 切换无效”：CSS 属性选择器的优先级战争

  现象：>/* 错误：权重低 */ [data-hf-frame="5"] { transform: scale(1.2); } /* 正确：用元素+属性组合，权重更高 */ button[data-hf-frame="5"] { transform: scale(1.2); } /* 或更彻底 */ .hf-ripple[data-hf-frame="5"] { transform: scale(1.2); }

  实操心得：在zcode hf-gen的输出 CSS 中，我们强制添加了元素类型前缀（如button.、div.），就是为规避此问题。永远不要相信“我的 CSS 写在后面就一定生效”。

  5.5 “时间轴不同步”：<timeclip>的currentTime设置时机

  现象：调用timeclip.currentTime = 10000后，子元素动画没跳转，仍停留在原位置。

  原因：<timeclip>是自定义元素，其currentTimesetter 必须在connectedCallback后才能安全使用。如果 JS 在 DOMContentLoaded 时就执行，而<timeclip>还未被浏览器解析（因为它是自定义标签），setter 会静默失败。

  解决方案：用customElements.whenDefined()确保：

  customElements.whenDefined('timeclip').then(() => { const tl = document.getElementById('game-timeline'); tl.currentTime = 10000; // 此时安全 });

  这是自定义元素的通用陷阱，但 hyperframes 重度依赖它，必须前置处理。我们已在zcode hf-build的注入脚本中，自动包裹所有timeclip操作。

  6. 扩展可能性：从单按钮到完整应用——hyperframes 的边界在哪里？

  hyperframes 不是银弹，它有明确的适用边界。我用它做过最复杂的项目，是一个 12 分钟的交互式产品演示，包含 37 个动画模块（产品旋转、参数图表、用户操作反馈），总 HTML + CSS 体积 1.2MB（gzip 后 320KB），在树莓派 4B 上流畅运行。但它不适合：

  • 需要实时物理计算的场景：如粒子系统、布料模拟。这些必须用 WebGL 或 WASM。
  • 用户生成内容（UGC）：hyperframes 的优势在于构建时确定性，而 UGC 要求运行时动态生成动画，CLI 链路不适用。
  • 超长视频（>10 分钟）：雪碧图会过大，需分段加载，此时<video>+MediaSource Extensions更合适。

  它的真正价值，在于重新定义“静态页面”的能力上限。热搜词里百度首页天气html制作、html一键返回顶部算法、css字体渐变，这些看似简单的功能，用 hyperframes 可以做到极致：天气图标不是 SVG，而是 24 帧的 PNG 序列，随温度变化平滑过渡；返回顶部按钮的箭头，不是transform: translateY()，而是 12 帧的位移序列，配合scroll-timeline实现视差滚动；字体渐变不是background-clip，而是 60 帧的 RGBA 渐变序列，每一帧精确控制每个字母的透明度。

  最后分享一个小技巧：在zcode hf-build的--watch模式下，你可以把设计师的 AE 工程文件（.aep）放在./design/目录，CLI 会监听.aep文件变更，自动调用 Adobe ExtendScript（通过 Node.js 的child_process）导出 JSON 设计稿，再触发后续流程。这样，设计师改完 AE，保存，5 秒后你的 HTML 就更新了——