@hy-bricks/devtools

@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