HyperFrames v0.6.113 解析AI Studio 集成面、Slideshow 解析器与图像 Alpha 命中测试实战【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames 是一个Write HTML. Render video.的 Agent 原生视频合成框架v0.6.1132026-06-19 发布把 AI Studio 会话式编辑所依赖的 SDK 集成面正式带上了线对象化的字体/图像变量、带词对齐的弹性时间控制、元素插入、关键帧动画操作全部落在 acorn GSAP 写入器上并统一收进 cutover 开关之后recast 仍为默认同时新增 slideshow 的 schema/parser/lint 规则以及第一阶段的图像 Alpha 命中测试让点击透明图像像素时事件可以穿透到后面的图层。本文基于 releases/v0.6.113.md 发布说明结合仓库源码逐项拆解这些能力的用法、底层实现与适用边界。版本总览一次面向 Agent 编辑体验的能力上线v0.6.113 的变更集中在三个方向SDK 编辑操作面WS-B / WS-C / WS-D / WS-3C变量与品牌资源支持对象化字体/图像值弹性时间控制elastic timing支持词级对齐新增addElement正向操作附带反向removeElementaddWithKeyframes与replaceWithKeyframes两个关键帧动画 SDK 操作落地。Slideshow 基础设施Core新增 slideshow schema、parser 与 lint 规则PR [#1580]。交互正确性Sdk图像 Alpha 命中测试第一阶段WS-G透明像素点击穿透到下层图层PR [#1574]。同时发布管线完成了两件内务把 acorn GSAP 写入器收进 cutover 开关、保持 recast 为默认WS-3F[#1573]hyperframes/sdk正式发布到 npm[#1587]。另有三个修复tag 单调性守卫收窄到 HEAD 可达标签、SDK 代码评审跟进WS-B/C/3C、引擎在闭区间 clip 末尾保持最后一帧视频[#1564]。对象化变量与品牌资源字体 / 图像不再只是字符串从标量到对象值WS-B此前 HyperFrames 的 composition 变量默认值是标量string / number / boolean / color / enum。v0.6.113 引入font与image两种对象化变量类型它们的值是一个 JSON 对象而不是可以写进 CSS 自定义属性里的字符串。SDK 类型定义给出了这两个对象的精确形状见 packages/sdk/src/types.ts/** font 变量 —— 对象值绝不写成 CSS 字符串 */ export interface FontValue { name: string; // CSS font-family 值 source: string; // 需要加载的样式表 URL } /** image 变量 —— 对象值绝不写成 CSS 字符串 */ export interface ImageValue { url: string; // 图片 src alt?: string; // 可选替代文本 fit?: cover | contain | fill | none | scale-down; // 可选 fit 模式 }setVariableValue的签名随之升级为接受string | number | boolean | FontValue | ImageValue见 packages/sdk/src/session.ts。值得注意的一个实现细节ImageValue有意没有使用[key: string]: unknown开放索引签名因为开放签名会让任何形如{url}的对象蒙混过关、吞掉键名拼写错误——类型层面就堵死了这类 bug。底层JSON 模型与 CSS 兼容通道的分离在 packages/sdk/src/engine/mutate.ts 的handleSetVariableValue中可以看到这条双通道写路径JSON 模型通道通过writeVariableDefault更新声明元素上的data-composition-variablesJSON这是驱动运行时runtime的主通道补丁路径是variablePath(id)。CSS 兼容通道标量值会同步到根元素的--{id}CSS 自定义属性供直接以 CSS 绑定变量的 composition 使用而对象值font/image不是合法的 CSS 自定义属性值此时cssCompatChange会清除任何残留的标量属性而不是强行写入。这意味着字体、图像这类资源型变量走 JSON 模型驱动运行时标量变量仍然同时保留 CSS 绑定这条兼容路径。两条通道各发各的补丁反向补丁也能精确恢复调用前的状态。另外 SDK 还强制校验变量 id 的合法形状^[A-Za-z_][A-Za-z0-9_-]*$见 packages/sdk/src/engine/mutate.ts原因是变量 id 会同时变成 CSS 自定义属性名--id、data-var-*属性值以及 CLI 的--variableskeySDK 是这些假设成立前的最后一道闸门。弹性时间控制与词对齐WS-C弹性时间elastic timing在 v0.6.113 中的形态是ElasticHold——给元素设置一个可伸缩的保持窗口。其类型定义见 packages/sdk/src/types.tsexport interface ElasticHold { start: number; end: number; fill: freeze | loop; }对应的 SDK 方法是一个薄封装见 packages/sdk/src/session.tssetHold(id: HfId, hold: ElasticHold): void { this.dispatch({ type: setHold, target: id, hold }); }底层handleSetHoldpackages/sdk/src/engine/mutate.ts把start、end、fill三个字段分别写入data-hold-start、data-hold-end、data-hold-fill属性并为每个字段生成独立的 RFC 6902 补丁对holdPath(id, field)保证 undo 时逐字段精确还原。fill只有两个合法值freeze冻结保持或loop循环保持。配套的还有时间信息读取与批量设置能力getElementTimings()读取每个带时间元素timed element的 enter/exit 时间与 GSAP 标签setElementTiming()在一个 batch 中批量分发setTimingop使历史记录只记一步 undo。文档注释里说明data-duration优先data-end −>addElement(parent: HfId | null, index: number, html: string): HfId底层实现有几个值得注意的守卫与细节空根/多根/script 防护parseInsertableFragment用临时 div 解析片段拒绝包含script的片段也拒绝多根节点确保插入的永远是单一可寻址根。ID 铸出防碰撞mintFragmentIds先收集文档中所有现存data-hf-id再对片段内未盖章元素逐一遍历铸新 id跳过EXCLUDED_TAGS新 id 永远不会与 composition 中已有元素冲突。铸出顺序是先铸 id → 再取 outerHTML → 再插入 → 最后构造补丁。插入语义按index定位参考节点index 子元素数量时退化为 appendRFC 6902 的 insert 语义。可逆性forward 补丁是patchAdd(newId, { html, parentId, siblingIndex })inverse 是patchRemove(newId)与handleRemoveElement的补丁语法恰好对称新元素 id 通过result.meta.newId返回供调用方后续继续引用。关键帧动画操作addWithKeyframes / replaceWithKeyframesWS-3C操作方法签名两个 SDK 方法packages/sdk/src/session.tsaddWithKeyframes( targetSelector: string, position: number, duration: number, keyframes: KeyframeSpec[], ease?: string, ): string; // 返回新动画 id失败返回 replaceWithKeyframes( animationId: string, targetSelector: string, position: number, duration: number, keyframes: KeyframeSpec[], ease?: string, ): string; // 返回替换后新动画 id可能不同于入参 id关键帧条目结构packages/sdk/src/types.tsexport interface KeyframeSpec { percentage: number; // 关键帧位置百分比 properties: Recordstring, number | string; // 该帧的属性值 ease?: string; // 可选缓动 auto?: boolean; // GSAP 端点标志落盘为数值 _auto: 1 而非布尔 }底层实现acorn 写入器与位置派生 ID 陷阱两个操作都经由hyperframes/core/gsap-writer-acorn的addAnimationWithKeyframesToScript/removeAnimationFromScript实现packages/sdk/src/engine/mutate.tsaddWithKeyframes直接向 GSAP script 追加一条关键帧动画通过meta.animationId返回新动画 id空 keyframes 被拦截op.keyframes.length 0直接返回空结果避免产生退化的keyframes: {}tween。replaceWithKeyframes先按 id 移除旧 tween再插入替代的关键帧 tween。这里有一个关键防御tween id 是位置派生的任何结构性编辑后都会重新编号所以一个过期的animationId可能解析到另一个tween。因此实现会先locateGsapAnimation校验该 id 当前定位到的动画的目标选择器是否仍与调用方期望一致若不一致或 tween 不存在则直接放弃afterRemove script时返回空而不是把 replace 静默降级成 add 造成重复 tween。替换后返回的 id 也是重新编号后的新 id。与既有 GSAP 操作的关系applyGsapOp的分发顺序是关键帧操作 → 弧线路径arc path操作 → withKeyframes 操作 → 常规 tween 操作见 packages/sdk/src/engine/mutate.ts。因此 v0.6.113 之前已有的addGsapTween/setGsapTween/removeGsapTween、关键帧微操作setGsapKeyframe、addGsapKeyframe、convertToKeyframes、materializeKeyframes等与新增的addWithKeyframes/replaceWithKeyframes并存覆盖从逐属性编辑到整体以关键帧替换的不同编辑粒度。另一个编辑正确性细节handleSetTimingpackages/sdk/src/engine/mutate.ts在移动/缩放 clip 时会同步 GSAP script 中匹配 tween 的 position 与 duration——因为播放时 GSAP script 才是时间真相DOM 属性编辑若不同步脚本将没有任何播放效果。该逻辑同时匹配data-hf-id与 DOMidStudio 面板可能以#domId写 tween并且跳过字符串位置如0.5、、的 tween——相对位置天然跟随邻居不能安全地按 clip 增量平移。这是一个明确注释的已知天花板ponytail使用时应知晓。cutover 开关与 recast 默认本次发布把 acorn GSAP 写入器收进 cutover 开关recast 仍是默认写入器WS-3F[#1573]。也就是说hyperframes/core/gsap-writer-acorn这条链路以及gsap-parser-acorn解析已经就绪但默认的生成/解析路径仍是 recast 系acorn 写入器需要显式切换才启用。对于集成方这意味着上面这些基于 acorn 的 SDK 操作是在 cutover 标志开启时才完整生效的路径默认配置下回退/兼容逻辑仍然以 recast 为准。使用前应结合当前版本的 cutover 配置确认实际写入器。Slideshowschema、parser 与 lint 规则Core定位与实现v0.6.113 新增了 slideshow 的 schema、parser 与 lint 规则[#1580]。Slideshow 解析器源码位于 packages/parsers/src/slideshow由四个文件组成slideshow.types.tsSlideshowManifest、SlideRef、ResolvedSlide、ResolvedSlideshow等类型定义parseSlideshow.tsmanifest 解析与解析期校验sceneId.ts场景 id 工具parseSlideshow.test.ts配套测试。packages/core/src/slideshow/index.ts只是一个向后兼容的 re-export解析器整体移到了hyperframes/parsers/slideshow说明该能力从 core 下沉到了 parsers 包core 侧保留导出以便旧导入路径不失效。数据形态JSON islandSlideshow 的 manifest 以 JSON island 形式内嵌在 composition HTML 中script标签的type为application/hyperframes-slideshowjson解析器parseSlideshowManifestpackages/parsers/src/slideshow/parseSlideshow.ts用正则匹配该 island 并JSON.parse随后通过一系列运行时类型守卫isManifest/isSlideRef/isSlideSequence校验结构非法则抛错。解析期校验规则resolveSlideshowpackages/parsers/src/slideshow/parseSlideshow.ts把 manifest 与场景时间范围结合产出ResolvedSlideshow和错误数组覆盖以下校验时间范围解析每条 slide 引用SlideRef的startTime/endTime与sceneId三种组合——两者都显式则直接用两者都缺则从场景的 start/duration 推出只给一个则从场景补齐缺失的边界场景不存在时给出明确的missingBoundError。非法时间endTime startTime会被标记。fragment 越界fragments 必须落在[start, end]区间内超出报错重复 fragment 去重并排序。sequence id 冲突重复的slideSequenceid 被标记保留最后一个定义。hotspot 目标校验hotspot 指向的 sequence 必须存在且非空。主线重叠检测主线上相邻 slide 按 start 排序后逐一比较curr.start prev.end即报重叠错误。这些校验把manifest 写错从播放期故障前移到了解析期配合新增的 lint 规则可在写入/提交前静态发现 slideshow 结构问题。图像 Alpha 命中测试透明像素点击穿透WS-G Phase 1解决的问题此前命中测试只判断点是否落在元素盒内。对带透明区域的 PNG/WebP 而言点击图片的透明像素会被图片本身拦截无法选中其下的图层。v0.6.113 的 Phase 1 让点击透明图像像素时事件穿透到后面的图层。实现位置与策略实现集中在 packages/sdk/src/adapters/iframe.ts该文件头部注释明确说明这是同源 iframe PreviewAdapter —— WS-A1命中测试 选择 WS-G图像 Alpha 命中测试Phase 1。几个关键实现策略文件内注释明确记录Canvas 缓存复用_imgCanvasCache让每张图片只画一次 canvas跨命中测试复用一次性为单次命中测试分配 OffscreenCanvas 在 4000×3000 图像上是内存灾难。跨域回退图片跨域或污染 canvas 时alpha 命中测试不可用回退为不透明opaque处理并打出带[hyperframes]前缀的警告日志——否则感觉不到命中测试生效见 iframe.ts 中相关注释。尺寸病态保护不为单次命中测试分配超大 canvasPathological-size guard。透明根节点匹配到的节点是[data-hf-root]时对命中测试透明见 iframe.ts 头注释。此外imageAlphaOpaqueAt被单独导出packages/sdk/src/adapters/iframe.ts供命中策略不同的宿主复用同样的墨迹ink测试逻辑。测试覆盖packages/sdk/src/adapters/iframe.test.ts 的注释说明 WS-G 的图像 Alpha 测试覆盖命中栈hit-test stack判定、控制 canvas 行为的 z-stack 图像 Alpha 测试等测试需要元素盒与计算样式而非简单的命中栈。Phase 1 的范围是基础穿透判定更复杂的场景如多种图片对象、交互反馈留待后续阶段。引擎修复闭区间 clip 末尾保持最后一帧Fixes 里有一项值得单独说明的引擎行为修复[#1564]在闭区间 clip 结束时刻保持最后一帧视频Hold the last video frame at the inclusive clip end。这修正了 clip 的end时刻本应包含在内inclusive却可能丢帧/黑帧的边界问题直接关系到片尾定格与剪辑衔接的播放正确性。发布与使用指引SDK 已发布 npmhyperframes/sdk在本次版本进入发布管线[#1587]可直接安装使用本文涉及的addElement、addWithKeyframes、replaceWithKeyframes、setVariableValue含 FontValue/ImageValue、setHold等 API。相对路径速查本文所有引用均以仓库根为基准SDK 操作类型与类型定义packages/sdk/src/types.tsSDK 会话 APIpackages/sdk/src/session.ts操作处理器与补丁生成packages/sdk/src/engine/mutate.tsSlideshow 解析器packages/parsers/src/slideshow/parseSlideshow.ts图像 Alpha 命中测试packages/sdk/src/adapters/iframe.ts写入器默认值提醒acorn GSAP 写入器当前在 cutover 标志之后、recast 为默认凡依赖gsap-writer-acorn的新能力请以当前版本的实际开关配置为准。小结v0.6.113 的价值在于把 AI Studio 会话式编辑所需的原子操作集补齐并收敛到 acorn 写入器对象化变量让字体/图片这类资源可被结构化地赋值与校验弹性时间与词对齐为口播/字幕类内容提供精确的时间控制addElement与关键帧动画操作让 Agent 能够以可撤销、可重放的补丁流编辑 composition。Slideshow 的 schema/parser/lint 三件套则把多场景演示文稿从约定俗成变成了可解析、可校验的一等公民。再加上图像 Alpha 命中测试的穿透语义这一版本为构建可靠的、由 AI Agent 驱动的视频编辑工作流补齐了关键拼图。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考