企业官网建设流程全解析

HyperFrames v0.6.120 热修复解析：npm 包入口恢复与页面侧 Shader 转场渲染修复

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

HyperFrames v0.6.120（发布于 2026-06-21）是一次面向发布链路与渲染正确性的热修复版本：一方面恢复已发布 npm 包的 Node 兼容入口，让 npm 消费者加载构建产物（JS 与声明文件）而非源码 TypeScript；另一方面修复页面侧（page-side）渲染中 shader 转场被丢弃、末场景内容在渲染末尾不可见的问题。读完本文，你将理解 HyperFrames 的双环境包导出机制（bun/node 条件导出）、页面侧 WebGL 合成器的两阶段捕获协议，以及如何通过回归测试守住渲染正确性。

版本概览

v0.6.120 是紧跟 v0.6.119 的第二个同日热修复（v0.6.119 修复的是幻灯片演示中的媒体控件问题）。本次修复集中在两个方向：

下文分别对这两个修复展开源码级解读。

一、Node 兼容包入口：从源码到构建产物的导出修正

问题本质

HyperFrames 仓库以 Bun 为主要开发/运行环境，因此在包内使用main、types、exports直接指向./src/*.ts源码（例如 packages/core/package.json 中的"main": "./src/index.ts"、"types": "./src/index.ts"）。这对 Bun 是友好的——Bun 可以直接运行 TypeScript；但对标准的 npm 消费者（Node.js + 常见打包器）而言，直接加载.ts源码会出现模块解析失败或缺少类型声明的问题。

条件导出（conditional exports）机制

packages/core/package.json 的exports字段对每个子路径都提供了多条件映射，例如：

{ "exports": { ".": { "bun": "./src/index.ts", "node": "./dist/index.js", "import": "./src/index.ts", "types": "./src/index.ts" } } }

关键点在于node条件：当消费者在 Node.js 环境下解析时，会命中./dist/index.js（构建产物），从而加载编译后的 JavaScript；types条件在publishConfig中则指向./dist/index.d.ts。

publishConfig：发布时覆盖

package.json中的publishConfig.exports会在 npm 发布时覆盖常规exports，保证发布到 npm registry 的包面向 Node 消费者全部指向dist产物：

"publishConfig": { "access": "public", "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" } } }

同时publishConfig.main/publishConfig.types分别为./dist/index.js与./dist/index.d.ts。也就是说，仓库内开发（Bun）走源码，发布后（Node）走构建产物——两套解析路径互不干扰。

package-subpaths.json：子路径清单的单一事实来源

仓库用 packages/core/package-subpaths.json 集中登记每个子路径的 source / runtime / types / environments 映射，例如：

{ "package": "@hyperframes/core", "localNodeRuntime": true, "subpaths": { ".": { "source": "./src/index.ts", "runtime": "./dist/index.js", "types": "./dist/index.d.ts", "environments": ["bun", "node"] } } }

从该文件可以看出，@hyperframes/core暴露了非常多的子路径（./canary、./beats、./variables、./compiler、./audio-fx、./color-grading、./storyboard、./runtime/*、./studio-api/*、./gsap-parser等），且绝大多数标记为"environments": ["browser", "bun", "node"]。v0.6.120 正是确保所有这些子路径在 Node 环境解析到dist/*.js与dist/*.d.ts，而不是错误地指向src/*.ts。

files字段（dist/**/*.js、dist/**/*.d.ts、dist/**/*.d.ts.map、dist/**/*.js.map）配合prepublishOnly脚本（当前为"echo skip"），确保构建产物被打包进 npm 包。可以推断，本次热修复的回归点在于：某些子路径的exports或publishConfig缺少node条件或错误指向了源码，导致 npm 消费者在 Node 下解析失败。

消费者侧的正确用法

对于使用@hyperframes/core的 npm 项目，修复后可以放心使用：

npm install @hyperframes/core

import { compile } from "@hyperframes/core/compiler"; import { init } from "@hyperframes/shader-transitions";

Node 环境会解析到dist下的 ESM 构建产物，TypeScript 类型来自对应.d.ts。对@hyperframes/shader-transitions，其 README 还列出了 ESM（dist/index.js）、CJS（dist/index.cjs）、IIFE（dist/index.global.js）三种分发格式，分别面向打包器、Noderequire()与<script>/CDN 场景。

二、Shader 转场：页面侧渲染的捕获与合成修复

背景：两条 shader 合成路径

HyperFrames 中 shader 转场（如glitch、domain-warp、light-leak等 WebGL 片元着色器转场）存在两条合成路径：

1. Node 侧分层管线（hf#677）：由 producer 的 Node-side layered pipeline 完成 shader 混合；
2. 页面侧合成（page-side compositing）：由浏览器页面内的 WebGL 合成器完成——这正是本次修复的对象。

页面侧合成的入口是window.__HF_PAGE_SIDE_COMPOSITING__ = true（由 producer 在EngineConfig.enablePageSideCompositing为 true 时注入），对应实现见 packages/shader-transitions/src/engineModePageComposite.ts。当该开关关闭时，hyper-shader 的 engine-mode 路径退化为仅做 opacity 翻转的时间线，由 Node 侧分层管线接管 shader 混合。

两阶段捕获协议

页面侧合成采用"两阶段捕获"协议（源码注释中有完整描述）：

• Phase 1（seek 包装，页面内执行）：运行原始 GSAP seek 定位时间线；若当前处于转场窗口内，将 FROM/TO 场景元素克隆进带layoutsubtree的 staging canvas，并置位window.__hf_page_composite_pending携带转场元数据，随后立即返回。
• Paint 强制（引擎侧，frameCapture.ts）：引擎检测到 pending 标志后，触发一次微型的Page.captureScreenshot，强制浏览器合成器绘制 staging canvas 克隆。
• Phase 2（引擎调用window.__hf_page_composite_resolve）：drawElementImage读取克隆体上已经有效的 paint 记录，上传纹理到 WebGL、运行 shader、显示 GL overlay，最后清理 staging canvas。

这套协议的优势在于：获得与预览路径drawElementImage一致的原生保真捕获，同时不依赖requestAnimationFrame触发绘制。

本次修复的两个具体缺陷

从源码中的修复痕迹可以还原 v0.6.120 修复的具体问题：

1. 末场景内容在渲染末尾不可见。在wrapSeek的非转场分支中，代码处理了"核心 clip 运行时会在合成结束前一刻隐藏最终场景"的行为——若 settled scene 的visibility是hidden，则强制恢复为visible（见settledSceneIdAt与相关注释）。这正是 release note 中"final-scene content remains visible through the end of the render"的实现依据：页面侧渲染此前直接把核心运行时隐藏末场景的状态截进了最终画面，导致结尾黑屏/内容缺失。

2. 转场中克隆体的尺寸坍缩与可见性。clonePinStyleFor处理了"仅用position:absolute; inset:0定位的场景根元素在克隆进 staging canvas 的 layout 子树后会坍缩为 0×0"的问题——克隆前先在活文档中测量getBoundingClientRect()，再把该精确盒模型（left/top/width/height）钉到克隆体上。同时，cloneNode会复制 GSAP 的 opacity 淡出（opacity:0/data-start），而 Chrome 不会绘制隐藏元素，drawElementImage会抛 "No cached paint record"，shader 退化成硬切——因此代码强制克隆体opacity:1; visibility:visible，并递归处理[data-start]子元素。可以推断，v0.6.120 之前的页面侧渲染在这些场景下会"丢弃" shader 转场，退化为 fallback DOM 状态。

配置开关与互斥约束

页面侧合成的开关在 packages/engine/src/config.ts 中定义：

• enablePageSideCompositing：默认true（DEFAULT_CONFIG中可见），可通过环境变量HF_PAGE_SIDE_COMPOSITING或编程式 API 覆盖；
• pageSideCompositingAutoDisabled：内部标记，记录"是 resolveConfig 自己关掉了页面侧合成"（区别于调用方显式传false）；
• 互斥约束：当useDrawElement（drawElement 快速捕获）与enablePageSideCompositing同时为 true 时，resolveConfig 会强制关闭页面侧合成（见 config.ts），理由是两者是互不兼容的捕获策略——drawElement 直接读取 paint 记录、绕过页面侧 prepare→composite→resolve 协议。强制关闭后，shader 转场回退到 Node 侧分层混合，而不是静默丢弃；同时记录pageSideCompositingAutoDisabled，以便后续 compile-time gate 恢复该标志而不覆盖调用方的显式配置。

此外，isPageSideCompositingSupported()（engineModePageComposite.ts）会做运行时探测：必须支持drawElementImage（Chrome 实验性 CanvasDrawElement API）且 WebGL 上下文可用，否则打印警告并回退到 opacity-flip 模式。

回归测试守门

仓库为本次修复配套了专门的回归用例 packages/producer/tests/page-side-shader-compositor-render-compat/：

• meta.json 描述：该用例覆盖"producer 复用浏览器 probe session 时页面侧 shader 转场捕获"的回归场景——脚本化音频音量强制走 probe 路径；shader 转场要求最终捕获页面在页面侧合成器 pre-head 脚本安装后重建，并使用 screenshot 捕获而非 BeginFrame。修复前，渲染出的 MP4 捕获到的是 fallback DOM 状态而非 shader 扭曲效果。质量门槛：minPsnr: 45、maxFrameFailures: 0、maxAudioLagWindows: 1。
• src/index.html 是一个 640×360 的演示合成：两个场景scene-a/scene-b，通过HyperShader.init({ scenes, transitions: [{ time: 0.75, shader: "glitch", duration: 0.85, ease: "none" }], timeline, compositionId })挂接 GSAP 时间线，并显式设置probeAudio.volume = 0.25以强制 probe 路径。

三、升级与验证建议

对于依赖 HyperFrames npm 包的消费者：

1. 升级到 v0.6.120（npm update @hyperframes/core或直接安装对应版本），确认 Node 环境下子路径导入（如@hyperframes/core/compiler、@hyperframes/core/gsap-parser）能解析到dist产物与类型声明；
2. 若 Node 环境仍命中.ts源码，检查是否有旧版 lockfile 缓存，或使用npm ls确认解析到的实际版本；
3. 对使用 shader 转场的渲染任务，升级后验证：
   • 转场窗口内画面为 shader 效果（而非硬切或 fallback DOM）；
   • 渲染结束帧中末场景内容保持可见，无提前隐藏/黑屏；
   • 若使用 drawElement 快速捕获（useDrawElement），确认页面侧合成被自动禁用并回退到 Node 侧分层混合（可观察pageSideCompositingAutoDisabled标记），转场仍正确输出。

小结

v0.6.120 是一发"小而关键"的热修复：包导出修正解决了 npm 生态下的可消费性问题，让 Bun 源码优先与 Node 构建产物优先两条路径各归其位；页面侧 shader 转场修复则补齐了两阶段捕获协议在真实渲染管线中的边界情况——克隆体尺寸、隐藏元素绘制、末场景提前隐藏。两者都可以在仓库源码（package.json、package-subpaths.json、engineModePageComposite.ts、config.ts）与回归测试（page-side-shader-compositor-render-compat）中找到直接证据，是理解 HyperFrames 发布与渲染管线的一个理想切面。

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