编写 HyperFrames 注册表贡献模板Caption / VFX / Component 与 registry-item.json 清单实战指南【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes本文面向想要为 HyperFrames 注册表贡献新 block 或 component 的开发者系统讲解官方推荐的 copy-paste 起始模板skills/hyperframes-registry/references/templates.md字幕Caption块的词级卡拉 OK 结构、VFX 块的 Three.js 状态代理渲染、可复用 Component 的 snippet 约定以及registry-item.json的 block / component 两种清单模板与标签分类。读完本文你可以直接用这些模板搭建一个能通过hyperframes lint与hyperframes check校验、并走完 PR 流程的注册表条目。HyperFrames 的注册表registry是可复用 block 与 component 的分发中心可通过hyperframes add name安装进任意项目。官方维护了一份“嵌入已验证模式”的起始模板集这些模板在脚手架阶段就把lint与check会检查的硬性规则内建到了代码里你只需要替换名称、字号、配色与动画即可而不是从零摸索。本文以该模板集为骨架结合仓库内的清单 Schema、真实条目与校验命令给出完整的实战路径。先厘清概念你要贡献的是 Block 还是 Component模板分两大体系根因是注册表里只有两类物品见 skills/hyperframes-registry/SKILL.mdBlockhyperframes:block完整的独立子合成sub-composition拥有自己的data-composition-id、固定画布尺寸如 1920×1080、固定时长和独立的 GSAP 时间线。字幕样式、VFX 效果、标题卡、lower third 都属于这一类通过宿主合成中的data-composition-src引入。Componenthyperframes:component没有自身尺寸与时长的可复用 snippetHTML CSS 可选 JS直接粘贴进宿主合成的 HTML 中跟随宿主合成的画布与时间线。CSS 效果、overlay、文字处理属于这一类。对应的贡献目录为registry/blocks/{block-name}/与registry/components/{component-name}/每个条目由{name}.html与registry-item.json组成详见 skills/hyperframes-registry/references/contributing.md。Caption 模板词级卡拉 OK 字幕块字幕是注册表中数量最多、规则最严的一类物品。官方模板把“单词级时间轴 组级进出场 卡拉 OK 高亮 硬性清除”的骨架一次写全你只需替换样式层。完整模板如下原样取自skills/hyperframes-registry/references/templates.md!doctype html html langen head meta charsetutf-8 / link hrefhttps://fonts.googleapis.com/css2?familyMontserrat:wght800;900displayswap relstylesheet / script srchttps://cdn.jsdelivr.net/npm/gsap3.14.2/dist/gsap.min.js/script style *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; } body { background: #111; overflow: hidden; } #root-BLOCKNAME { position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #111; } .cap-container { position: absolute; top: 0; left: 0; width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; } .cg { position: absolute; display: flex; align-items: center; justify-content: center; gap: 32px; max-width: 1700px; overflow: visible; opacity: 0; visibility: hidden; } .cw { font-family: Montserrat, sans-serif; font-weight: 900; font-size: 128px; color: #ffffff; text-transform: uppercase; line-height: 1; display: inline-block; -webkit-text-stroke: 3px rgba(0, 0, 0, 0.8); paint-order: stroke fill; text-shadow: 0 4px 12px rgba(0, 0, 0, 0.5); } /style /head body div idroot-BLOCKNAME >!doctype html html langen head meta charsetutf-8 / script srchttps://cdn.jsdelivr.net/npm/gsap3.14.2/dist/gsap.min.js/script script srchttps://cdn.jsdelivr.net/npm/three0.147.0/build/three.min.js/script style *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; } body { background: #030308; overflow: hidden; } #root-BLOCKNAME { position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #030308; } #canvas-BLOCKNAME { position: absolute; top: 0; left: 0; width: 1920px; height: 1080px; } /style /head body div idroot-BLOCKNAME >!doctype html html langen head meta charsetutf-8 / script srchttps://cdn.jsdelivr.net/npm/gsap3.14.2/dist/gsap.min.js/script style *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; } body { background: transparent; overflow: hidden; } .COMPNAME-wrap { position: absolute; inset: 0; overflow: hidden; pointer-events: none; } /style /head body div classCOMPNAME-wrap !-- Your reusable effect/overlay here -- /div script (function () { // Component snippet — no>{ $schema: https://hyperframes.heygen.com/schema/registry-item.json, name: BLOCKNAME, type: hyperframes:block, title: Human-Readable Title, description: One sentence: what it does and who uses it, dimensions: { width: 1920, height: 1080 }, duration: 10, tags: [category, subcategory], files: [ { path: BLOCKNAME.html, target: compositions/BLOCKNAME.html, type: hyperframes:composition } ] }Component 变体无dimensions、无duration{ $schema: https://hyperframes.heygen.com/schema/registry-item.json, name: COMPONENTNAME, type: hyperframes:component, title: Human-Readable Title, description: One sentence: what it does, tags: [category], files: [ { path: COMPONENTNAME.html, target: compositions/components/COMPONENTNAME.html, type: hyperframes:snippet } ] }按类别推荐的标签Tags by categoryCaptionscaptions、viral、professional、karaoke、minimalVFXthree-js、particles、shader、gpuTransitionstransition、shader、wipe、dissolveBlockslower-third、social、title-card、data-vizComponentseffect、overlay、text-treatment清单字段的 Schema 级约束模板字段并不是随意的仓库里的正式 Schemadocs/schema/registry-item.json对每个字段都有硬约束理解它能避免写出“看起来对但校验不过”的清单必填字段name、type、title、description、files。namekebab-case正则约束为^[a-z0-9](https://link.gitcode.com/i/bd5a337a051e4a52ef0331667bd12d2b)?$——只能小写字母数字与连字符且必须以字母数字开头和结尾。type枚举hyperframes:example、hyperframes:block、hyperframes:component。dimensions/duration的条件约束Schema 的allOf逻辑规定——type为hyperframes:component时禁止出现dimensions与duration其余类型则必须同时具备两者duration必须大于 0。这正是两套模板差异的底层依据。files[].type枚举五种——hyperframes:composition独立合成block 用、hyperframes:snippetcomponent 用、hyperframes:asset、hyperframes:style、hyperframes:timeline。files[].path相对registry-item.json的源路径files[].target用户项目中的目标路径Schema 明确禁止..越界段与绝对路径。path指向BLOCKNAME.html、target指向compositions/BLOCKNAME.htmlcomponent 则指向compositions/components/COMPONENTNAME.html两者一一对应。可选字段tags、author、authorUrl、licenseSPDX 标识如Apache-2.0、MIT、minCliVersion、deprecated、registryDependencies、previewvideoposter等。真实条目对照data-chart 与 caption-clip-wipe仓库中已合并的条目可以验证模板的实际落地形态。registry/blocks/data-chart/registry-item.json是 block 变体的完整实例name: data-chart、type: hyperframes:block、dimensions: { 1920, 1080 }、duration: 15、tags: [data, chart, statistics]文件指向data-chart.html→compositions/data-chart.html类型为hyperframes:composition还带preview视频与海报。registry/components/caption-clip-wipe/registry-item.json则是 component 变体的实例无dimensions/duration文件类型为hyperframes:snippet标签使用captions、caption-style、wipe、clip-path、reveal等。写你自己的清单时直接以这两份真实文件为参照比对着模板更稳。命名约定与脚手架所有条目都遵循“2–3 字母 ID 前缀”约定因为 block 会被作为子合成嵌入宿主component 会被粘贴进宿主元素 ID 若不加前缀极易与宿主或其他条目冲突。官方约定示例见 skills/hyperframes-registry/references/contributing.md条目名ID 前缀示例 IDcap-hormozihzhz-cg-0,hz-cw-3cap-typewritertwtw-cg-0,tw-ch-0-5vfx-chromevcvc-canvas在registry/blocks/{block-name}/或registry/components/{component-name}/下先放好{name}.html与registry-item.json再按类型套用上文对应模板。若要实现逐字符动画typewriter、scramble需把每个字符包成span id{prefix}-ch-{group}-{char}并用tl.set按单词时间戳计算交错间隔——注意光标/装饰元素也要用tl.set而不是 CSS animation因为 CSS 动画不可被时间线 seek。从模板到合并校验、预览与发布模板只保证“起点正确”最终能否进注册表取决于是否通过质量门禁。贡献流程共六步Clarify → Scaffold → Build → Validate → Preview → Ship详见 skills/hyperframes-registry/references/contributing.md。校验Step 4——本地把规则跑一遍hyperframes lint # 0 errors required hyperframes check --no-contrast # 0 console errors required预览Step 5——渲染视频、截图做视觉 QA、发布到 hyperframes.dev 供评审# Render preview video hyperframes render -o preview.mp4 # Snapshot for visual QA hyperframes snapshot --at 1.0,3.0,5.0,7.0 # Publish to hyperframes.dev for review npx hyperframes publish发布Step 6——所有步骤缺一不可缺失任何一步都会产生损坏的目录条目# 1. Create branch git checkout -b feat/registry-{name} # 2. Format HTML npx oxfmt registry/{kind}/{name}/*.html # 3. Regenerate registry/registry.json from the item directories. # Do not hand-edit it: an entry added by hand survives until the next # regeneration and then vanishes, and one left behind for a directory that # no longer exists is worse, because hyperframes add name resolves the # name and then fails on missing files. npx tsx scripts/generate-registry-items.ts # 4. Generate catalog docs page npx tsx scripts/generate-catalog-pages.ts # 5. Publish to hyperframes.dev so reviewers can preview npx hyperframes publish # 6. Stage everything git add registry/{kind}/{name}/ registry/registry.json docs/catalog/ # 7. Commit git commit -m feat(registry): add {name} — {one sentence} # 8. Push and open PR with hyperframes.dev link git push origin feat/registry-{name} gh pr create --title feat(registry): {name} --body preview: {hyperframes.dev-url}其中{kind}是blocks或components。注意registry/registry.json是由scripts/generate-registry-items.ts从条目目录自动重新生成的聚合清单禁止手改——手写条目会在下次重新生成时消失而目录已删除却残留的条目更糟hyperframes add name能解析到名称却取不到文件直接失败。目录预览图按{kind}存放在docs/images/catalog/{kind}/{name}.png若registry-item.json声明了preview目录卡片使用其posterURL。收尾自检清单合并前对照以下质量门禁逐项打勾源自 skills/hyperframes-registry/references/contributing.mdhyperframes lint→ 0 errorshyperframes check→ 0 console errorsnpx oxfmt --check通过registry/registry.json已包含新条目已运行scripts/generate-catalog-pages.ts生成文档页已运行npx hyperframes publish认领项目 URL预览 MP4 已附在 PR 中外部贡献者或目录 PNG 已上传内部贡献者所有 ID 唯一且带前缀参考资源模板集原文skills/hyperframes-registry/references/templates.md完整贡献流程Clarify → Ship 六步skills/hyperframes-registry/references/contributing.md清单字段正式 Schemadocs/schema/registry-item.jsonBlock 接入宿主合成data-composition-src等属性skills/hyperframes-registry/references/wiring-blocks.mdComponent 合并进宿主合成skills/hyperframes-registry/references/wiring-components.md真实 block 实例registry/blocks/data-chart/registry-item.json真实 component 实例registry/components/caption-clip-wipe/registry-item.json运行时文字适配 API 实现packages/core/src/text/fitTextFontSize.ts【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考