HyperFrames v0.7.17 深度解读hyperframes/lint 浏览器端零依赖校验入口与 hyperframes/parsers 依赖收敛【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframesHyperFrames v0.7.17发布于 2026-06-27的核心变化只有一个主题让hyperframes/lint规则引擎彻底摆脱 Node.js 运行时获得一个可完全在浏览器中运行的hyperframes/lint/browser入口同时把该包的依赖收敛到唯一的内部包hyperframes/parsers。读完本文你将掌握浏览器端调用lintHyperframeHtml/lintMediaUrls/shouldBlockRender的完整方式、这次依赖重构涉及的工具函数迁移与向后兼容策略以及 CSSurl()正则防 ReDoS 加固的实现细节。版本概览v0.7.17 改了什么根据版本发布记录 releases/v0.7.17.md本版本包含三类变更Features新增hyperframes/lint/browser入口——一个无 Node 依赖的客户端规则引擎暴露lintHyperframeHtml、lintMediaUrls、shouldBlockRender三个 API面向纯浏览器编辑器与工具Internalhyperframes/lint的依赖从hyperframes/core收窄为仅hyperframes/parsers共享的 URL/资产路径、字体别名、幻灯片解析工具迁入hyperframes/parsers并在 core 中保留向后兼容存根同时加固 CSSurl()正则防御多项式级 ReDoSDocs Examples新增 parsers、lint、studio-server 三个包的独立文档页对应 docs/packages/lint.mdx、docs/packages/parsers.mdx、docs/packages/studio-server.mdx。下面逐项结合当前仓库源码展开。浏览器入口hyperframes/lint/browser零 Node 依赖的客户端校验API 表面与使用方式浏览器入口的源文件是 packages/lint/src/browser.ts其头部注释明确定位HTML-string in, findings out — withzero Node.js dependencies: nonode:fs, no filesystem, no server.它只导出两类内容四个类型HyperframeLintSeverity、HyperframeLintFinding、HyperframeLintResult、HyperframeLinterOptions三个函数lintHyperframeHtml、lintMediaUrls来自 hyperframeLinter.ts和shouldBlockRender来自 shouldBlockRender.ts。典型浏览器端用法与 docs/packages/lint.mdx 中 Browser usage 一节一致import { lintHyperframeHtml, shouldBlockRender } from hyperframes/lint/browser; const result await lintHyperframeHtml(htmlString, { filePath: index.html }); if (!result.ok) { for (const f of result.findings) console.warn(f.code, f.message); }边界划分lintProject遍历项目目录、依赖文件系统刻意不在浏览器入口中导出它只存在于主入口 packages/lint/src/index.ts 中供 Node 环境使用。文档页 docs/packages/lint.mdx 也用醒目的 Info 框强调了这一点浏览器入口包含everything that operates on an HTML string目录级 lint 必须走主入口。核心 API 的语义lintHyperframeHtml(html, options)是规则引擎本体hyperframeLinter.tsexport async function lintHyperframeHtml( html: string, options: HyperframeLinterOptions {}, ): PromiseHyperframeLintResult { const startedAt performance.now(); const ctx buildLintContext(html, options); const { findings, timings } await runRules(ctx, options.filePath); // ... 按 severity 统计 errorCount / warningCount / infoCount return { ok: errorCount 0, errorCount, warningCount, infoCount, findings, timings }; }optionsHyperframeLinterOptions定义于 types.ts支持四个字段字段类型说明filePathstring?文件路径用于回填每条 finding 的file字段isSubCompositionboolean?标记被校验的是子合成sub-compositionexternalStylesArray{href, content}?外链样式表内容供样式相关规则分析distributedboolean?面向分布式 / Lambda 渲染场景时置true会将system_font_will_alias规则从info提升为warning因为该场景下系统字体别名替换不会发生字体将静默回退到 OS 默认字体返回的HyperframeLintResult除ok等于errorCount 0与三级计数外还带timings: LintTimingstotalMs、按规则组聚合的groupMs、以及最慢单条规则的slowestRule/slowestRuleMs方便定位性能异常。lintMediaUrls(html, { timeoutMs? })是第二条异步检查路径它会扫描 HTML 中所有video/audio/img/source的src属性仅http(s)://开头的远端地址逐个发起带AbortController超时的HEAD 请求默认超时 8000ms对返回非 2xx 或网络异常的 URL 生成inaccessible_media_url错误级 findinghyperframeLinter.ts。文档建议的用法是先跑lintHyperframeHtml再合并lintMediaUrls的结果。shouldBlockRender(strictErrors, strictAll, totalErrors, totalWarnings)是一个纯函数渲染门禁shouldBlockRender.tsreturn (strictErrors totalErrors 0) || (strictAll (totalErrors 0 || totalWarnings 0));即strictErrors模式下仅错误阻断渲染strictAll模式下错误与警告都阻断。由于它不依赖任何 Node API可以安全地从浏览器入口导入——这正是它被单独抽到 shouldBlockRender.ts 并由browser.ts直接再导出的原因。规则引擎的组织方式规则在 hyperframeLinter.ts 中按来源模块分为 9 个组共约 86 条规则const RULE_GROUPS [ { group: core, rules: coreRules }, { group: media, rules: mediaRules }, { group: gsap, rules: gsapRules }, { group: captions, rules: captionRules }, { group: composition, rules: compositionRules }, { group: adapters, rules: adapterRules }, { group: textures, rules: textureRules }, { group: fonts, rules: fontRules }, { group: slideshow, rules: slideshowRules }, ];规则源文件位于 packages/lint/src/rules/ 目录core.ts、media.ts、gsap.ts、captions.ts、composition.ts、adapters.ts、textures.ts、fonts.ts、slideshow.ts及其同名测试文件。引擎在runRules中对每条规则单独计时、按组聚合并用code|severity|selector|elementId|message组成的键去重保证两条规则命中同一问题只报一次。LINT_RULE_COUNT与LINT_RULE_GROUP_COUNTS两个导出常量被 CLI 侧消费——例如 packages/cli/src/telemetry/lintRun.ts 引入它们用于遥测使跨版本比较 lint 结果时能识别规则集变化。规则能捕获的典型问题与 docs/packages/lint.mdx 的 What the Linter Catches 列表一致包括缺少window.__timelines时间线注册、未静音的video导致自动播放失败、可见定时元素缺少classclip、弃用属性名、缺少data-width/data-height合成尺寸、指向不存在 clip ID 的data-start以及一批 GSAP 相关确定性风险规则如gsap_relative_value_second_writer、gsap_repeat_refresh_relative_value、gsap_function_value_hazard、gsap_callback_dom_measurement、non_deterministic_code和 SVG 描边陷阱规则svg_drawon_css_dasharray_conflict、svg_measure_before_path_d、gsap_timeline_set_initial_hide。编译期保证 测试期验证浏览器入口的零 Node 依赖不是靠口头约定而是双重保障编译期packages/lint/tsup.config.ts 为browser.ts单独配置了一个platform: browser、target: es2022的构建任务。注释写得很直白platform: browsermakes the buildFAILif anynode:*builtin sneaks into the rule engine — a compile-time guarantee。主入口则单独构建为target: node22、platform: node。发布产物的映射由 packages/lint/package.json 中publishConfig.exports决定.→dist/index.js./browser→dist/browser.js。测试期packages/lint/src/browser.test.ts 从浏览器入口实际导入并运行lintHyperframeHtml验证无文件系统访问即可产出结构化结果同时用三个断言钉死shouldBlockRender的三态逻辑strictErrors下 1 错 0 警 → 阻断0 错 3 警 → 不阻断strictAll下 0 错 1 警 → 阻断。依赖收敛从hyperframes/core到仅hyperframes/parsers发布说明称本版本installing the validator no longer pulls the studio server or other unrelated packages。对照当前仓库的 packages/lint/package.jsondependencies只有dependencies: { hyperframes/parsers: workspace:*, htmlparser2: ^10.1.0, linkedom: ^0.18.12, postcss: ^8.5.8, postcss-selector-parser: ^7.1.4 }hyperframes/core已从依赖列表中移除唯一的内部依赖是hyperframes/parsers——这解释了为什么 v0.7.17 必须先做下一节的工具函数迁移lint 引擎用到的 URL/资产路径、字体别名、幻灯片解析能力原本住在 core 里必须先搬家到 parsers才能安全地切断 core 依赖而不改变行为。这个单一事实来源架构在 docs/packages/lint.mdx 中被明确表述CLI 的hyperframes lint命令与渲染期的 render-gate消费同一套规则引擎。从源码可以印证这条调用链CLI 侧的 packages/cli/src/utils/lintProject.ts 直接export { lintProject, shouldBlockRender } from hyperframes/lint渲染侧的 packages/core/src/compiler/staticGuard.ts 也import { lintHyperframeHtml } from hyperframes/lint。工具函数迁移与向后兼容存根本次 Internal 变更的另一半是搬家共享的 URL/资产路径工具、字体别名font-alias工具、幻灯片解析器slideshow-parser从 core 迁入hyperframes/parsers原位置保留back-compat stubs再导出存根保证旧导入继续工作。当前仓库中这些存根清晰可查每行注释统一为 Moved to hyperframes/parsers. Re-exported here for back-compat.存根文件core 内说明packages/core/src/compiler/assetPaths.ts资产路径工具packages/core/src/compiler/rewriteSubCompPaths.ts子合成路径重写packages/core/src/fonts/aliases.ts字体别名packages/core/src/slideshow/index.ts幻灯片解析packages/core/src/utils/urlPath.tsURL 路径工具lint 包自身对 core 的旧导入路径也有同样的兼容处理packages/core/src/lint/index.ts 一行export * from hyperframes/lint且 packages/core/src/index.test.ts 中有专门测试项 exposes lintHyperframeHtml via the hyperframes/core/lint back-compat stub 验证该存根可用。迁移后的新归属体现在 packages/parsers/package.json 的子路径导出中例如./slideshow→dist/slideshow.js、./asset-paths→dist/assets.js。文档建议见 docs/packages/lint.mdx旧代码hyperframes/core/lint仍可解析但新代码应直接导入hyperframes/lint。安全加固CSSurl()正则的 ReDoS 防御发布说明提到 hardened the CSSurl()regex against polynomial-ReDoS。加固后的正则在 packages/parsers/src/assetPaths.ts/** * Regex matching CSS url(...) references — captures the quote style and the * raw URL. The URL group is anchored to non-whitespace at both ends so the * surrounding \s* can never overlap it (avoids polynomial-ReDoS backtracking); * the captured value is whitespace-bounded already, matching the old behavior * after callers .trim() it. */ export const CSS_URL_RE /\burl\(\s*([]?)(^)\s]*[^)\s])?)\1\s*\)/g;从源码结构看加固思路是URL 捕获组的首尾都锚定到非空白字符[^)\s]使外层的\s*与捕获组之间不存在可重叠的边界——多项式级回溯的经典来源正是相邻量词对同一串空白存在多种切分方式。注释同时说明捕获值本身已是空白边界封闭的与旧行为在调用方.trim()之后保持语义一致因此这是一次纯防御性重写不改变匹配结果。该正则被资产路径扫描/重写逻辑共用文件头注释列出的消费方rewriteSubCompPaths、collectExternalAssets、localizeExternalAssets也即 lint 与 CLI 发布流程共享同一份解析层——这与lint 只依赖 parsers的架构是自洽的。配套文档parsers / lint / studio-server 包页面v0.7.17 的 Docs 变更补充了三个包的独立文档页均已存在于当前仓库docs/packages/lint.mdx安装方式npm install hyperframes/lint、适用场景Node 中 lint 整个项目 / 单个 HTML 字符串 / 渲染门禁 / 自定义 UI 与 CI 展示、完整 API 示例、浏览器用法与规则能力清单docs/packages/parsers.mdxlint 所依赖的 HTML GSAP 解析层docs/packages/studio-server.mdxStudio 服务端包说明。在仓库中验证仓库为只读参考以下是可执行的验证方式需先完成工作区依赖安装# 运行 lint 包全部测试含浏览器入口的 browser.test.ts cd packages/lint bun test # 或 npx vitest run # 查看浏览器入口暴露的 API cat packages/lint/src/browser.ts # 查看双目标构建配置node22/browser 两套 tsup 任务 cat packages/lint/tsup.config.tsbrowser.test.ts的用例设计本身就是验收标准无文件系统访问、result.ok为布尔值、result.findings为数组即证明规则引擎在纯客户端可运行。小结v0.7.17 是 HyperFrames lint 体系的一次架构性小步快跑hyperframes/lint/browser让 composition 校验第一次完全脱离 Node.js 与服务器往返浏览器编辑器可以在任何网络调用之前完成客户端验证同时通过把共享解析工具下沉到hyperframes/parsers并保留 core 存根把依赖图从lint → core拖入 studio server 等收敛为lint → parsers这一条最细的路径并顺手以一条锚定非空白边界的正则封堵了 CSSurl()解析的 ReDoS 面。对 Agent 与 CI 集成方而言本版本后的使用建议是Node 侧统一从hyperframes/lint导入目录级校验用lintProject浏览器侧从hyperframes/lint/browser导入字符串级校验渲染门禁统一用shouldBlockRender保持两处行为一致。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考