@hy-bricks/devtools

HyperCard 运行时诊断 SDK — 浮窗 UI + 3 个探针,装上自动启用,生产环境可关。

📦 当前发布版 0.6.3 ── 与 @hy-bricks/core 同步(fixed 组同版本号)。逐版变更以 CHANGELOG 为准;0.4.2 起浮窗已交付实时运行时错误流 + 多画布场景诊断 + Events Tab。

解决什么问题

当画布上的组件"不听话"时,这个 SDK 帮你定位原因:

| 你遇到的问题 | 用哪个探针 | |---|---| | 为什么点不中(命中区域 / z-index / event blocker) | inspectHitTest(canvasId, canvasPt) | | 为什么拖不动(drag 状态机 / 输入事件丢失) | inspectDrag(canvasId, instanceId) + 事件 ring buffer | | 为什么渲不出来(组件未注册 / props 校验失败 / 异常) | inspectRender(canvasId) |

装上后会在页面右下角注入一个浮窗,点开就能看到三组实时数据,无需翻 console。

安装

pnpm add @hy-bricks/devtools @hy-bricks/canvas @hy-bricks/core vue

@hy-bricks/canvas / @hy-bricks/core / vue@^3.5 是 peerDependencies,需要在宿主项目里一起装。

快速接入

import { enableHyBricksDiagnostics } from '@hy-bricks/devtools'

if (import.meta.env.DEV) {
  enableHyBricksDiagnostics({
    canvases,                                    // CanvasHandle[]
    ui: true,
    level: 'debug',
    probes: ['hit-test', 'drag', 'render'],
    captureDomRects: true,
  })
}

只想 dev 环境零配置启用?用 auto subpath:

import '@hy-bricks/devtools/auto'

配置选项

| 字段 | 类型 | 默认值 | 说明 | |---|---|---|---| | canvases | CanvasHandle[] | [] | 要诊断的画布句柄,通常从 @hy-bricks/canvas 拿到 | | ui | boolean | true | 是否注入浮窗 UI;关掉只跑采集层 | | level | 'silent' \| 'error' \| 'warn' \| 'info' \| 'debug' | 'warn' | 日志级别 | | probes | Array<'hit-test' \| 'drag' \| 'render'> | 全部 | 只启用部分探针 | | captureDomRects | boolean | false | 是否抓取 DOM 包围盒,定位命中区域更直观但有开销 |

浮窗 UI 风格

• 深紫黑半透明 + backdrop-blur 玻璃感
• 大圆角胶囊容器、内部按钮圆角
• Active 按钮:蓝色实心 + 微微辉光;Inactive:透明背景,灰 icon
• isolation: isolate 锁 stacking,不会被宿主 dialog 反向覆盖

UI 不依赖宿主 Tailwind — 用纯 scoped CSS + CSS variables。lucide-vue-next 提供图标。

已交付(0.4.2)

• 实时 runtime 错误流 ── 渲染 Tab 内"运行时错误"栏,实时显示 instanceId + error.message + 可展开 stack(同 id+message 250ms 内合并计数)
• 多画布场景诊断 ── 画布 mount/unmount 实时反映到顶部选择器;HyperCardPageRenderer 自动注册诊断 handle,runtime 场景全 Tab 生效

路线图(Roadmap)

• Sentry / OpenTelemetry adapter
• 面向终端用户的简化 UI

配合使用 / Ecosystem

• @hy-bricks/core — 运行时核心
• @hy-bricks/canvas — 自由画布(devtools 的 peerDep)
• @hy-bricks/editor — 嵌入式编辑器

License

MIT © hy_top