企业官网建设流程全解析

HyperFrames v0.7.106 Catalog 更新解析：真实合成预览、变量面板与侧边栏分组

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames v0.7.106（发布于 2026-08-11）是一次围绕 Catalog（组件目录）体验的系统性升级：Catalog 页面开始直接播放真实合成而不是录好的视频，358 个条目按创作意图被归入 8 个可折叠分组，每个带变量的条目都重新拥有了可交互的变量面板，且重装条目不再覆盖你的手工编辑。读完本文，你将完整掌握这批变更的用法、背后的数据流实现（变量如何从面板经链接与安装命令到达渲染管线），以及重装保留编辑的 CLI 行为。

版本概览：一次 Catalog 工作流的整体升级

v0.7.106 的变更清单横跨 Studio、Catalog、CLI、Registry 与文档五个部分，核心脉络非常清晰：让 Catalog 从"看视频"变成"用起来"。发布说明开篇即点明三件事：

• Catalog 页面在播放器中运行真实的合成（composition），而不是一段录制好的预览视频；
• 侧边栏将358 个条目按"你来做什么"组织成8 个可展开的分组；
• 每个声明了变量的条目都配有可编辑面板：修改值后预览立即用新值重建，分享链接携带这些值，复制出来的安装命令也会把变量值一并带上。

这三点叠加的效果是：从浏览、试调到安装，整条链路不再有"预览归预览、安装归安装"的割裂感。下文逐项拆解，并给出仓库内对应的实现证据。

Catalog 页面播放真实合成（不再是录制视频）

变更内容

此前 Catalog 详情页的预览是一段预先渲染好的录制视频；v0.7.106 通过 Play the real composition on catalog pages（PR #3168）将其替换为真实运行中的合成——你在预览里看到的就是会被渲染引擎逐帧执行的同一份 HTML。

这一点在文档侧有直接呼应：目录总览页 docs/catalog/index.mdx 使用<hyperframes-player>元素，通过srcdoc加载条目的真实 HTML 载荷来播放：

<script type="module"> const item = await fetch("/public/catalog/blocks/ai-chat-reveal.json").then((response) => response.json(), ); const player = document.createElement("hyperframes-player"); player.setAttribute("srcdoc", item.html); player.setAttribute("controls", ""); player.setAttribute("autoplay", ""); player.setAttribute("muted", ""); player.setAttribute("loop", ""); document.body.appendChild(player); </script>

而目录总览的轮播组件 docs/snippets/catalog-overview-player.jsx 更进一步：它内置了一个包含 11 个分区（Code Animations、Captions、HTML-in-Canvas、Social Overlays、Lower Thirds、Shader Transitions、CSS Transitions、Showcases、Data、Effects、Blocks）的场景清单，每 2.5 秒自动切换一个分区，fetch对应条目的 JSON 载荷后用hyperframes-player的srcdoc属性加载并 seek 到指定媒体时间点，从而实现"一条视频式导览"：

async function show(index) { var token = ++request; var scene = scenes[index]; try { var html = await compositionFor(scene); if (token !== request) return; var player = document.createElement("hyperframes-player"); player.setAttribute("srcdoc", html); player.setAttribute("controls", ""); player.setAttribute("muted", ""); player.addEventListener("ready", function () { player.seek(scene.mediaStart || 0); if (!reduced) player.play(); }, { once: true }); // ... } }

注意组件还处理了prefers-reduced-motion（reduced标志）：系统开启"减少动态效果"时自动停止轮播与自动播放，这对视频预览页面是必要的可访问性细节。

例外：canvas drawElement 预览仍保留录制视频

同一批变更中有一条看似矛盾的条目——Keep the recorded video for canvas drawElement previews（PR #3171）。原因在于：使用 canvasdrawElement的条目，其真实渲染依赖特定的图形环境与时机，实时回放无法稳定还原；因此这类预览保留录制视频。这说明"真实合成预览"是逐条目权衡的结果，而非一刀切——无法被播放器忠实回放的合成，退回录像是为了保证预览始终可见。从catalog-overview-player.jsx中也能看到同样的双轨设计：HTML-in-Canvas分区就走的是video字段（videoComposition包装一段<video>）而非catalog载荷。

侧边栏按创作意图分组：8 个分区收纳 358 个条目

变更内容

Group the sidebar by what you came to make（PR #3194）重新组织了 Catalog 侧边栏的导航逻辑。分组维度从"技术类型"改为**"你来做这件事"**（what you came to make），358 个条目被归入 8 个可折叠的 section，且目录总览页明确给出了这两大类入口：

• Blocks（块）：较大的完整场景或自包含视觉，例如 App Showcase；
• Components（组件）：嵌入已有场景的小型效果或行为，例如caption-kinetic-slam。

这与你打开条目后的实际体验一致：动效预览在上、下方是"Install（安装）→ 把自然语言请求丢给 Agent → 替换示例内容 → 在完整视频里复查"的流程（见 Use an item 一节）。

从生成管线看，Catalog 页面由 scripts/generate-catalog-pages.ts 程序化生成。该脚本会解析已生成页面中手写的## sections（见脚本中 "Pull the hand-written## sectionsout of an already-generated page" 的CarriedContent逻辑），保证"人类手写章节 + 机器生成章节"能共存并保持顺序；侧边栏分组正是这套结构化输出的一部分。分组数据源则是 docs/public/catalog-index.json——一份包含每个条目name、type（block/component）、title、description、tags、href与preview的索引清单，358 个条目的侧边栏即由它驱动。

变量面板回归：改值、分享、安装一条龙

变更内容

Put the variables panel back, on payloads（PR #3199）是本次更新的重头戏。发布说明描述了完整闭环：

1. 每个声明了变量的条目，页面都会渲染一个可编辑的变量面板；
2. 你在面板里改值，预览会用新值重建（rebuilds with your values）；
3. 分享链接会保留这些值（a link keeps them）；
4. 安装命令会携带这些值（the install command copies with them attached）。

这条链路在源码里有非常完整的实现证据，值得深入拆解。

变量在载荷里如何声明

先看数据侧。Catalog 条目的 JSON 载荷（如 docs/public/catalog/blocks/ai-chat-reveal.json）把变量声明写在 HTML 根元素的data-composition-variables属性上，ai-chat-reveal 这个 block 一共声明了 15 个变量，例如：

{ "id": "botName", "type": "string", "role": "content", "label": "Assistant name", "description": "Title in the chat header.", "default": "Assistant" }, { "id": "ecHeadline", "type": "string", "role": "content", "label": "End-card headline", "description": "Closing card headline. A | breaks the line.", "default": "It's not magic.|It's HTML." }

每个变量携带id、type、role（content/style/timing/motion/layout 之一）、面向人的label/description以及default。这与你写自定义合成时在data-composition-variables里的声明方式完全一致，完整字段契约可查 docs/concepts/variables.mdx 与 docs/reference/html-schema.mdx。变量类型支持string、number、color、boolean、enum、font、image七种，类型决定面板渲染哪种控件、也决定渲染阶段能否拦截非法值。

面板如何让预览"用新值重建"：hfv 查询串与单层 iframe 重载

变量面板组件在 docs/snippets/variables-explorer.jsx。它的注释把这个机制讲得很清楚：

A composition reads its variables once, at init, before any of this exists. So there is no "apply" path into a live one — the value has to be present before the composition boots.

合成只在初始化时读取一次变量，不存在"运行中注入"的通道。因此面板不能直接给运行中的合成发消息，而是通过 scripts/generate-catalog-pages.ts 生成的预览包装器，把值写进查询串，然后只重载内层合成 iframe，页面、包装器与面板本身从不闪动，并把播放头（playhead）一起带过去：

• variableBootstrap(ownFile)生成一段内联脚本：读取location.search里的hfv参数（用URLSearchParams.get解码），解析为 JSON 存入window.__hfVariables，再把它写到指向本文件的data-composition-src宿主元素的data-variable-values属性上——这保证值在任何运行时脚本之前就已就位；
• variablePreviewWrapper(src)生成包装器：监听postMessage（event.data.hfVariables），收到新值后player.setAttribute('src', BASE + '?hfv=' + values)触发单层iframe 重载，并用arm(resumeAt)轮询把播放头 seek 回原位置继续播放。

关于为什么用查询串而不是消息通道，源码注释给出了严谨的理由："Values travel in the query string rather than a message into the composition because they have to be readable before its first script runs."（值必须在合成第一个脚本运行前就可读。）且每一跳都用encodeURIComponent编码、URLSearchParams.get解码，规避了 form 编码下空格+与%20的歧义。

面板侧还有一个重要的工程细节——防抖：注释明确指出 "the post is debounced. A dragged range input fires an event per pixel, and an unthrottled reload per pixel is a reload storm that never settles."（拖拽 range 控件每个像素触发一次事件，不节流就是一场永不停止的重载风暴）。所以控件本身实时跟手，但 postMessage 重载被防抖合并；install-command.jsx与面板通过 URL query string 这一共享状态通信，面板更新 URL 时广播hf-vars-changed事件、popstate覆盖后退按钮场景。

链接如何保留值：URL 即共享状态

"链接保留值"的实现同样藏在 docs/snippets/install-command.jsx 的注释里：面板与安装命令是 MDX 里两个没有父组件关系的独立组件，"The URL is the shared state rather than a prop"。面板把当前值序列化进 URL（参数形如?vars-<item>=<JSON>），分享出去后，任何人打开这个链接，面板与安装命令都能从 query string 恢复同一组值——不需要任何后端状态。

安装命令如何携带变量：--vars

安装命令组件 docs/snippets/install-command.jsx 挂载后读取URLSearchParams(window.location.search).get('vars-' + item)，解析出变量对象后，在标准安装命令后面追加--vars参数：

const parsed = JSON.parse(raw); // ...校验必须是对象且非空 setTuned(` --vars '${JSON.stringify(parsed)}'`);

于是页面上展示的安装命令从：

npx hyperframes add app-showcase

变成携带了你调好变量的版本：

npx hyperframes add app-showcase --vars '{"botName":"Claude","ecCta":"Get Started"}'

这与你直接用 CLI 渲染带变量的合成是同一套语法——docs/concepts/variables.mdx 中的渲染示例：

npx hyperframes render \ --variables '{"title":"Enterprise","accent":"#22c55e"}' \ --strict-variables \ --output enterprise.mp4

--strict-variables会把未声明或类型错误的渲染值从警告升级为错误，npx hyperframes lint则能提前拦截声明缺失、默认值类型错误与非法 enum 选项。批量场景可配合--batch rows.json（每行一个变量对象）与--output "renders/{name}.mp4"占位符逐行渲染；--batch-concurrency默认单行并发，需在单个真实渲染稳定且内存充足时才应调高。

CLI 重装保留编辑：不再覆盖你的修改

变更内容

Keep your edits when you reinstall a catalog item（PR #3193）修复了此前的一个破坏性行为：重复安装（reinstall）同一 Catalog 条目会覆盖你之前的编辑。v0.7.106 之后，若目标文件已被你修改过，重新执行npx hyperframes add <item>会保留你的改动，而不是无提示地写回原始模板。

这对真实工作流的价值很大：Catalog 条目的设计哲学是"安装后归你所有"（install and own），你会替换示例文案、调整配色、增删段落——这些手工成果不应因为一次重装而蒸发。与"安装命令携带变量"配合起来，完整的推荐流程是：先在 Catalog 页面用变量面板调好值 → 复制带--vars的安装命令 → 安装后基于初始变量值继续编辑，且后续重装安全。

其他 Catalog 与 Registry 变更

v0.7.106 的 Catalog 小节还包含几条值得注意的细节变更：

• Registry 带回 video-primitive 动效（Bring back the video-primitive moves，PR #3169）：一批 video-primitive 类组件（例如 catalog-index.json 中arc-motion-path这类携带video-primitive标签的 GSAP 运动原语）重新进入 Registry。这类组件通常依赖 packages/player 播放器的原生能力，因此也解释了为何播放器在 Catalog 预览中的地位持续提升。
• 脚本按名称解析资源（Resolve assets a script loads by name，PR #3170）：合成脚本运行时按名称加载的资源，现在能被正确解析，解决了此前脚本引用资源路径解析失败导致预览与渲染不一致的问题。
• Media Use 成本分层从 Registry 派生（Derive provider cost tier from the registry，PR #3155）：Media Use 相关流程不再硬编码服务商成本档位，而是从 Registry 数据派生，避免文档与实现两处维护导致漂移。

Registry 条目的结构契约定义在 docs/schema/registry-item.json：每个条目必须声明name（kebab-case）、type（hyperframes:example/hyperframes:block/hyperframes:component三选一）、title、description与files；block 与 example 强制要求dimensions和duration，而 component 明确禁止携带这两项（schema 中的allOf条件约束）；files[].target被显式禁止包含..或绝对路径，保证安装不会逃逸出项目根目录。这为上面"重装保留编辑"和"按名称解析资源"提供了数据层的保障。

Studio 修复与文档更新

• 修复：读取 rotate 属性测量元素角度（Read the rotate property when measuring an element's angle，PR #3163）：此前 Studio 测量元素角度时遗漏了rotate属性，导致含旋转的布局在时间线/画布上的角度测量不准，本版修复。
• 文档：周报 2026-08-03 至 08-10（PR #3154）：docs/changelog.mdx 维护的每周摘要同步更新。
• 文档：写清楚 Studio 不会告诉你的事（PR #3165）：新增/扩充了 Studio 的使用边界说明，帮助用户理解 Studio 哪些信息不显示、需要从源码侧确认——这与本版"Catalog 展示真实合成"的思路一致：文档与实现对齐，减少黑盒。
• 内部：重新生成 skills manifest（PR #3203），并格式化 packages/studio/AGENTS.md（PR #3167），均为工程维护性变更。

从 v0.7.106 看 Catalog 的演进方向

把 v0.7.106 的变更放在一起看，可以提炼出 Catalog 工作的三条主线（均为可从源码确认的工程判断，而非承诺）：

1. 预览即真身：能实时播放的合成，一律播放真实合成（PR #3168）；播放器无法忠实的场景（canvas drawElement）才退回录像（PR #3171）。预览与最终渲染之间的"所见非所得"缝隙被系统性收窄。
2. 值在源头生效：变量面板、分享链接、安装命令共用 URL query string 作为共享状态（hfv、vars-<item>），配合variableBootstrap的"值先于脚本就位"设计（scripts/generate-catalog-pages.ts），保证变量从浏览到渲染全程一致。
3. 安装可重复、可保留：--vars让首次安装就带参数，重装保留编辑（PR #3193）让后续迭代不丢工作——安装行为从"一次性拉取"变成"可持续演进的本地资产"。

如果你需要在自己的合成里复刻这套变量体验，仓库已经给出了完整范本：用data-composition-variables声明变量 → 用data-var-text/data-var-src/ CSS 自定义属性（var(--accent)）做直接绑定 → 复杂逻辑再用window.__hyperframes.getVariables()编程读取；嵌套合成用data-variable-values给同一份源码的不同实例传不同值（详见 docs/concepts/variables.mdx 的 "Give each nested composition different values" 一节）。最后的防线是npx hyperframes lint+--strict-variables，把变量契约问题挡在渲染之前。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes