HyperFrames v0.7.22 版本全解SDK 编辑能力统一解析resolveEditingAffordances、CLI 发布与 Lint/Engine 可靠性修复【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.22发布于 2026-06-30是一次以编辑器生态开放为核心的里程碑版本它把此前内聚在 Studio 内部的元素可编辑能力判定抽象成了跨包共享的resolveEditingAffordancesAPI含核心纯函数与浏览器端 SDK 适配器让自定义编辑器也能回答这个元素现在能编辑什么同时落地了hyperframes publish --public公开发布、hyperframes feedback --file-issue一键提交带可复现链接的工单、Storyboard 视图默认开启以及一批针对 Lint、Engine 编码与 CLI 可靠性的修复。读完本文你将掌握 v0.7.22 的新 API 用法、底层判定规则以及本次所有 CLI/Lint/Engine 变更的来龙去脉。版本总览本次更新要解决什么问题v0.7.22 的发行说明releases/v0.7.22.md把这次更新概括为一句话让hyperframes/sdk成为一等公民的编辑引擎。围绕这一目标本次变更分为四类Features4 项共享的resolveEditingAffordances编辑能力解析核心层 Studio 重定向 SDK 浏览器适配器、publish --public公开发布、feedback --file-issue一键提工单、Storyboard 视图默认开启。Fixes13 项覆盖 LintThree.js ESM 识别、字体与 GSAP 误报、EngineH.264/H.265 奇数尺寸补齐、CLI错误输出、渲染摘要、HTTP Range、git 不可用兜底等。Docs Examples2 项完整的 SDK 参考文档与指南明确根合成时长是编译期常量这一语义。下文按新特性深挖 → 实战集成 → 可靠性修复 → 文档变更的顺序逐项展开。核心特性一resolveEditingAffordances——统一元素可编辑能力的单一事实源在 v0.7.22 之前某个元素现在能不能移动、能不能改样式、该显示哪些编辑面板这类判定逻辑散落在 Studio 内部实现里SDK 消费者无法复用。本次更新将其收敛为纯函数 浏览器适配器 Studio 复用的三层结构单一事实源位于核心包核心纯函数resolveEditingAffordances/resolveEditingSectionspackages/core/src/editing/affordances.ts浏览器端 SDK 适配器resolveElementAffordancespackages/sdk/src/editing/affordances.tsStudio 编辑面板的复用入口薄封装保持向后兼容packages/studio/src/components/editor/domEditingLayers.ts。从源码注释可以确认设计意图Pure, DOM-free editing-affordance resolution. Single source of truth for what the studios edit panel (and any SDK consumer) surfaces per selected element。核心层完全不触碰 DOM不调用getComputedStyle由调用方把归一化事实实时或静态喂进来hyperframes/sdk/editing子路径才是浏览器专属的事实提取器Studio 内部也有一套自己的映射器两条路径共用同一份核心判定逻辑避免漂移。输入EditableElementFacts事实集合判定不是直接传 DOM 节点而是传一组结构化事实定义见 affordances.ts事实字段含义Studio / SDK 取值来源hasStableTarget是否存在稳定的补丁目标Studio 用selector\|hfIdSDK 模型中恒为truetag小写标签名如div、video、audio、imginlineStyleskebab-case 内联样式能力判定只读left/top/width/height/transformel.style.getPropertyValue(...)computedStyleskebab-case 计算样式缺失时canMove/canResize默认falsegetComputedStyle提取的 6 个属性isCompositionHost/isCompositionRoot是否为子合成宿主 / 根合成SDK 场景默认falseisInsideLockedComposition/isMasterView是否处于锁定合成内部 / 主视图Studio 概念existsInSource元素是否存在于源码模型中SDK 传modelEl ! nullhasEditableText是否有可编辑文本Studio 看textFields.length 0SDK 看model.text ! nullhasTimingStart是否带data-startSDK 看model.start ! null否则读属性animationCount指向该元素的 GSAP tween 数量SDK 取model.animationIds.length输出一capabilities——八项能力开关DomEditCapabilitiesaffordances.ts定义了八项布尔能力与一个reasonIfDisabled说明字段canSelect能否选中脚本生成元素、锁定合成内元素各有差异canEditStyles能否直接编辑样式canCrop能否做非破坏性的clip-path: inset()裁剪canMove/canResize能否直接编辑作者化的left/top/width/height字段canApplyManualOffset/canApplyManualSize/canApplyManualRotation画布拖拽/缩放手柄对应的手动变换能力reasonIfDisabled当上述能力被禁用时给出人类可读的原因文案。输出二sections——哪些编辑面板适用EditingSectionApplicabilityaffordances.ts回答选中的元素应该展示哪些检查器分区text、media、colorGrading、timing、animation、layout、audioFx、style。源码注释给出几条关键设计决策audio元素从不绘制可见盒因此layout与style对它恒为falsehf-audio-group是混音总线mixer bus没有视觉框也没有自身媒体但携带data-fx-chain——选中它必须能打开 Audio FX 机架因此audioFx对它为true同时timing恒为false总线没有data-start、没有时长其自动化时钟是合成时间colorGrading仅对video与img为true且只是元素级能力消费方仍需自行 AND 自己的功能开关。核心特性二SDK 浏览器适配器resolveElementAffordances与实战集成SDK 侧暴露的入口是resolveElementAffordancespackages/sdk/src/editing/affordances.ts完整文档见 docs/sdk/guides/editing-affordances.mdx自hyperframes/sdk0.7.22起通过hyperframes/sdk/editing子路径提供。签名与入参import { resolveElementAffordances } from hyperframes/sdk/editing; function resolveElementAffordances( liveEl: HTMLElement, modelEl: PickHyperFramesElement, text | animationIds | start | null, ctx?: AffordanceContext, ): EditingAffordancesliveEl合成 iframe 中已完成布局的 DOM 元素。适配器内部会对其调用getComputedStyle因此必须是已挂载到渲染文档中的节点modelElSDK 模型元素comp.getElement(id)的结果脚本生成的元素传null——此时existsInSource为false进入仅可选中模式ctxStudio 专属概念的上下文isCompositionHost、isCompositionRoot、isInsideLockedComposition、isMasterView独立自定义编辑器可整体省略全部默认false。端到端示例按能力条件渲染检查器官方指南 editing-affordances.mdx 给出了完整的集成路径配合 openComposition 与 iframe 预览适配器使用import { openComposition, createIframePreviewAdapter } from hyperframes/sdk; import { resolveElementAffordances } from hyperframes/sdk/editing; const iframe document.querySelectorHTMLIFrameElement(#composition-frame)!; const preview createIframePreviewAdapter(iframe, (op) comp.dispatch(op)); const comp await openComposition(compositionHtml, { preview }); function onElementSelected(hfId: string) { // 1. 从 iframe 取实时 DOM 元素 const liveEl iframe.contentDocument?.querySelectorHTMLElement( [data-hf-id${hfId}], ); if (!liveEl) return; // 2. 取 SDK 模型元素——脚本生成元素为 null const modelEl comp.getElement(hfId); // 3. 解析可编辑能力 const { capabilities, sections } resolveElementAffordances(liveEl, modelEl); // 4. 条件渲染控件 renderInspector({ capabilities, sections, hfId }); } function renderInspector({ capabilities, sections, hfId }) { // 编辑被锁定时展示禁用态提示 if (!capabilities.canEditStyles capabilities.reasonIfDisabled) { showDisabledBanner(capabilities.reasonIfDisabled); return; } if (capabilities.canEditStyles) showStylePanel(hfId); // 仅对绝对定位且有 px 值的元素展示位置/尺寸字段 if (capabilities.canMove) showPositionFields(hfId); if (capabilities.canResize) showSizeFields(hfId); // 画布拖拽手柄看 canApplyManualOffset而不是 canMove if (capabilities.canApplyManualOffset) showDragHandles(hfId); // 分区面板 if (sections.text) showTextPanel(hfId); if (sections.media) showMediaPanel(hfId); if (sections.colorGrading myFeatureFlags.colorGrading) showColorGradingPanel(hfId); if (sections.timing) showTimingPanel(hfId); if (sections.animation) showAnimationPanel(hfId); }关键坑点Gotchas指南 editing-affordances.mdx 明确警告四类易错点纯浏览器 API适配器内部调用getComputedStyle严禁在 Node、服务端 action 或任何非浏览器路径导入这正是核心纯解析器与浏览器适配器分层的原因需要已布局的 DOMcanMove/canResize依赖实时计算出的position/left/top若在 iframeload事件或首帧渲染前同步调用两个标志都会是falsenull模型 仅可选中脚本生成元素canSelect: true但所有编辑能力为false且带reasonIfDisabled文案可保留选中高亮但隐藏编辑控件canApplyManualOffset≠canMovecanMove要求绝对/固定定位 作者化 px 值 无 transform 驱动几何而基于 translate 的画布拖拽applyDraft/commitPreview流程以canApplyManualOffset为闸门参见 Canvas Integration。底层判定规则从核心源码看能力是如何计算出来的能力解析resolveCapabilities核心实现 affordances.ts 按优先级依次短路无稳定目标或处于锁定合成整体不可编辑锁定合成内连canSelect都为falsereasonIfDisabled给出 belongs to a locked composition 或 could not resolve a stable patch target脚本生成元素不在源码中仅canSelect: true文案为 generated by a script and cannot be edited visually合成根canEditStyles: true但canCrop/canMove/canResize全部为false——根定义了画布/预览边界无可裁剪对象常规元素进入几何判定。position必须为absolute或fixed且left/top有可解析的 px 值且transform为恒等变换canMove才为truecanResize再要求width或height存在。值得注意canCrop对子合成宿主依然为true裁剪是持久化在父源中宿主上的视口裁剪即使其内部样式需要钻入编辑。其中parsePx是唯一的 px 解析器affordances.tsStudio 的 domEditingDom 会重新导出它以杜绝两条路径漂移isIdentityTransform则用容差 0.0001 判定matrix/matrix3d是否为恒等affordances.ts。分区解析resolveEditingSectionsresolveEditingSections 只读标签与事实标志、不读样式因此已持有 capabilities 的调用方如 Studio 面板可以免重复解析几何。核心规则包括text有可编辑文本且非合成宿主、非锁定合成内mediavideo | audio | imgaudioFx仅audio或音频总线colorGrading仅video | imgtiming非总线且有data-start或有动画animationanimationCount 0且标签非audio且非总线——audio剪辑和总线没有 transform/opacity/boxtween 在它们身上动不了任何东西但audio保留timing剪辑照常上时间线。测试用例佐证配套的 affordances.test.ts 用 20 个用例锁定这些规则锁定合成内不可选且带原因、脚本生成元素仅可选、合成根可改样式但不可裁剪、子合成宿主在主视图中样式锁定但可裁剪、transform 驱动的几何阻断canMovematrix(1,0,0,1,5,5)非恒等、内联left/top覆盖缺失的 computed、computedStyles缺失时canMove/canResize默认 false、audio有 timing 无 animation 而总线两者皆无等。这些用例既是行为契约也可作为自定义编辑器复刻判定时的参考实现。CLI 新特性publish --public公开发布v0.7.22 为hyperframes publish增加了--public标志实现见 packages/cli/src/commands/publish.ts。从源码可以确认其语义默认发布是私有的——Upload the project to a stable URL (private by default)public参数默认false加--public后Make the claimed project public to anyone, not just the claimer任何人持有 URL 即可观看无需登录源码中还处理了一个细节原地重复发布不带--public时不发送任何可见性参数让服务端保留该目录此前的可见性状态避免把已公开的项目误降级为私有。相关示例与说明# 私有发布到稳定 URL默认 hyperframes publish # 发布特定目录 hyperframes publish ./my-video # 让已声明的项目对任何人公开 hyperframes publish --public # 原地更新已发布项目 hyperframes publish --update url|id # 发布到共享团队空间 hyperframes publish --space space-id # 跳过确认提示脚本场景 hyperframes publish --yes--update目标解析parseUpdateTargetpublish.ts支持从完整 URL、无 scheme 的 URLnew URL会拒绝、带?query/#hash的链接中提取/p/id片段或直接接受裸 id。对应测试 publish.test.ts 验证了可见性提示、默认入口预检以及重复发布不擅自声明可见性等行为。CLI 新特性feedback --file-issue一键提交带复现链接的工单另一个提升反馈闭环的 CLI 特性是hyperframes feedback --file-issuepackages/cli/src/commands/feedback.ts把当前项目发布为最小复现包然后打开一个预填好的 GitHub issue 草稿草稿中包含该公开链接与你的反馈内容由你审阅后手动提交不会自动提交。hyperframes feedback --rating 3 --comment GSAP timeline froze --file-issue源码显示其优雅降级策略发布复现包失败时返回undefined工单仍会打开只是不带链接Filing the issue without a repro link.并配套--dir指定要发布为复现包的项目目录与--yes跳过发布 提工单的确认提示。提交前会明确告知提工单会把项目发布到公开 URL。StudioStoryboard 视图默认开启v0.7.22 移除了 Storyboard 视图的特性开关feature flag使其默认可用#1794 与 docs/studio/index.mdx。Lint 修复Three.js ESM 识别与两处误报消除识别通过 ESM URL/路径导入加载的 Three.js此前 Lint 无法识别通过 ESM URL/路径导入而非传统 script 标签加载的 Three.js会把正常的 Three.js 代码误判。v0.7.22 让 lint 规则能识别这种加载方式#1805该文件同时承载 Three.js 识别与 GSAP 重叠 tween 判定。font_family_without_font_face不再误报 system-ui 字体栈与var()字体规则实现见 packages/lint/src/rules/fonts.ts本次修复#1796围绕两点系统字体栈GENERIC_FAMILIES集合fonts.ts现在完整覆盖system-ui、ui-serif、ui-sans-serif、-apple-system、blinkmacsystemfont、inherit/initial/unset/revert等关键字——它们由引擎解析为 OS UI 字体不是可安装文件绝不能因缺少font-face被标记即使后面跟着通用回退如-apple-system, system-ui, sans-serifvar()间接引用normalizeUsedFontNamefonts.ts对任何带括号的函数 token 返回null——var(--heading)是静态无法解析的间接引用字面量var(...)不是字体名标记它是误报var(--x, Inter)这种带回退的写法会在回退部分留下悬空的)同样需要跳过。此外该规则还有两个已注释的设计细节先stripCssComments去掉 CSS 注释防止注释里的}截断font-face\s*\{[^}]*\}块匹配导致漏看真实font-family见 #1534 上下文以及system_font_will_alias规则仅在分布式/Lambda 渲染options.distributed下激活——本地渲染时系统字体替换是渲染器按设计工作不是缺陷。overlapping_gsap_tweens不再误报互不相同的未解析目标overlapping_gsap_tweens是检测同一元素上重叠 GSAP tween 的规则packages/lint/src/rules/gsap.ts。此前它会把两个互不相同的未解析选择器当成同一个元素两者都落到统一的__unresolved__占位符见 gsap.ts从而产生两个不同元素 tween 重叠的误报。v0.7.22 的修复#1798让未解析目标保持各自独立只有真正解析到同一元素时才判定重叠。Engine 修复奇数输出尺寸补齐到偶数H.264/H.265 编码器对画面宽高有偶数对齐要求。v0.7.22 的 Engine 修复#1802 与 packages/engine 的源码与测试目录。其余 CLI 可靠性修复汇总v0.7.22 还包含一批提升 CLI 可靠性与可用性的修复全部落在 packages/cli/src不再打印[object Object]validate/inspect 的报错路径改为结构化输出#1810git 不可用时跳过 AI skills 安装避免在无 git 环境如 CI 沙箱中安装 skills 失败阻塞命令#1803feedback 无渲染时长时不输出避免记录伪造的时长#1797渲染摘要显示输出视频时长而非渲染耗时#1812项目媒体以 HTTP Range 方式伺服让 validate 能读取 WAV 时长#1811Studio 遥测过滤运行时生成节点resolver-shadow 遥测不再混入脚本动态生成的节点#1795。示例与文档更新SDK 综合参考与指南本次为 SDK 补齐了完整的参考文档与指南#1817、docs/sdk/reference 下的 adapters/composition/edit-operations/open-composition/types/utilities以及 docs/sdk/guides 下的 canvas-integration、editing-affordances、embedded-override-mode、persistence、querying-and-editing、timing-and-animation、undo-redo-and-patches 等指南kinetic-type 示例素材托管把 kinetic-type A-roll 视频素材托管到仓库内保证该示例真正可渲染#1799语义澄清根合成的时长是编译期常量不能通过 script 或--variables参数在运行时参数化#1818——这对在脚本中动态设置合成时长的用户是重要的行为边界。升级建议与总结如果你是 SDK 自定义编辑器使用者v0.7.22 的核心动作是将hyperframes/sdk升级到0.7.22从hyperframes/sdk/editing导入resolveElementAffordances用它替换自己手写的元素类型 → 面板映射并牢记四条 Gotchas浏览器专属、需已布局 DOM、null 模型仅可选、拖拽看canApplyManualOffset。如果你是 CLI 用户可以立即体验publish --public与feedback --file-issue带来的发布与反馈闭环如果你在 Lambda 上做分布式渲染本次的system_font_will_alias语义、奇数尺寸补齐与 git 兜底都会让链路更稳。Lint 侧的font_family_without_font_face与overlapping_gsap_tweens误报修复则让hyperframes lint在真实工程尤其是带框架级样式表与复杂 GSAP 时间线中的可信度进一步提升。完整的逐版本变更可对比 releases 目录下的版本说明查阅。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考